Payins
A payin is one payment attempt. You create it from your backend, send the customer to its checkout link, and NetPay tells you when it is paid.
Create a payin
POST /v1/payinsHTTP
curl https://api.netpay.ph/v1/payins \
-H "Content-Type: application/json" \
-H "X-Api-Key: npk_live_..." \
-H "X-Timestamp: $TS" \
-H "X-Signature: $SIGNATURE" \
-H "Idempotency-Key: order-10042" \
-d '{
"merchant_order_id": "ORD-10042",
"amount": "1250.00",
"channel": "QRPH",
"description": "Order 10042",
"customer": { "name": "Juan Dela Cruz", "email": "[email protected]" },
"success_url": "https://yourshop.example/thanks",
"failure_url": "https://yourshop.example/checkout?retry=1",
"metadata": { "cart": 991 }
}'201 CreatedJSON
{
"status": "success",
"data": {
"payin_no": "PI26110800AB12CD34EF",
"merchant_order_id": "ORD-10042",
"mode": "LIVE",
"status": "PENDING",
"channel": "QRPH",
"amount": "1250.00",
"fee": "25.00",
"net_amount": "1225.00",
"currency": "PHP",
"fee_breakdown": { "percent": "2.0000", "fixed": null },
"checkout_url": "https://netpay.ph/pay/3f9c...",
"expires_at": "2026-11-08T12:30:00+08:00",
"paid_at": null
},
"request_id": "req_6a1f..."
}| Field | Type | Required | Description |
|---|---|---|---|
merchant_order_id | string | Yes | Your order number, 1-64 characters, unique within your account. |
amount | string | Yes | In pesos with up to 2 decimals, inside your account limits (see GET /v1/channels). |
channel | string | No | QRPH (default), GCASH, MAYA or INSTAPAY. |
description | string | No | Shown on the checkout page, up to 255 characters. |
customer | object | No | name, email, mobile. |
success_url / failure_url | string | No | Where the checkout sends the customer afterwards. Must be https and, if you set allowed return domains, one of them. |
callback_url | string | No | Webhook URL for this payin only. Defaults to the one on your Developers page. |
metadata | object | No | Anything you want back on the webhook, up to 4 KB. |
A payin below its fee is refused
If the fee would be equal to or above the amount, the request answers AMOUNT_BELOW_FEE. Check the fee in advance with GET /v1/fees/quote.
Statuses
| Status | Meaning |
|---|---|
PENDING | Created; the customer has not paid yet. |
PROCESSING | The processor is confirming the payment. |
SUCCEEDED | Paid. The net amount is in your pending balance. |
FAILED | The payment did not go through. |
EXPIRED | Not paid before the checkout expired. |
CANCELLED | Cancelled by you or the customer before payment. |
Final statuses never change. Read a payin back with GET /v1/payins/{payin_no}, list them with GET /v1/payins, or cancel an unpaid one with POST /v1/payins/{payin_no}/cancel.