Create a payment
https://api.payerfox.com/api/v1/paymentsCreates a payment and returns a hosted checkout_url. Send the customer there to pay.
Headers
AuthorizationstringRequiredBearer followed by your API key.
e.g. Bearer pd_test_…
Content-TypestringRequiredAlways application/json for request bodies.
e.g. application/json
Idempotency-KeystringOptionalRecommended. Retrying with the same key returns the original payment instead of creating a second one. Use your order ID.
e.g. ORDER-1001
Body — 14 fields
amountstringRequiredAmount as a decimal string, in the currency’s normal decimals.
e.g. "499.00"
currencystringRequiredISO currency code (max 10), e.g. INR, USD, USDT.
e.g. "INR"
merchantOrderIdstringOptionalYour order ID (max 255). Returned as merchant_order_id in responses and webhooks so you can match the order.
e.g. "ORDER-1001"
descriptionstringOptionalShown to the customer on checkout and in your dashboard.
e.g. "Pro plan — 1 month"
orderItemsarrayOptionalUp to 100 line items. Each: name (required, max 255), quantity (default 1), unitPrice, sku (max 80), currency. Shown on the payment and sent in webhooks as order_items.
e.g. [{ "name": "Pro plan", "quantity": 1, "unitPrice": "499.00", "sku": "PRO-1M" }]
customerNamestringOptionalCustomer name (max 200).
e.g. "Asha Verma"
customerEmailstringOptionalCustomer email (max 200). Searchable in the dashboard.
e.g. "asha@example.com"
customerPhonestringOptionalCustomer phone (max 40).
e.g. "+919800000000"
successUrlurlOptionalWhere the customer returns after paying.
e.g. "https://yourstore.com/success"
cancelUrlurlOptionalWhere the customer returns if they cancel.
e.g. "https://yourstore.com/cancel"
ipnUrlurlOptionalWebhook URL for this payment only. PayerFox POSTs payment.paid here.
e.g. "https://yourstore.com/webhooks/payerfox"
gatewaystringOptionalPayment method code (e.g. paytm_upi_qr, binance_c2c, razorpay). Must be enabled for your website. Omit to let the customer choose on checkout.
e.g. "paytm_upi_qr"
tagsstring[]OptionalLabels on the payment. Use them to filter payments (GET /payments?tag=…) and to route the payment to the connected account that has the same tag.
e.g. ["subscription", "vip"]
metaobjectOptionalAny extra JSON you want back, e.g. your user ID or plan. Returned as meta in responses and webhooks. Keys customer, customerName/Email/Phone and orderItems/items are read as the fields above instead.
e.g. { "userId": "u_8812", "plan": "pro" }
Request
curl -X POST "https://api.payerfox.com/api/v1/payments" \
-H "Authorization: Bearer pd_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ORDER-1001" \
-d '{
"amount": "499.00",
"currency": "INR",
"merchantOrderId": "ORDER-1001",
"description": "Pro plan — 1 month",
"orderItems": [
{
"name": "Pro plan — 1 month",
"quantity": 1,
"unitPrice": "499.00",
"sku": "PRO-1M"
}
],
"customerName": "Asha Verma",
"customerEmail": "asha@example.com",
"customerPhone": "+919800000000",
"successUrl": "https://yourstore.com/success",
"cancelUrl": "https://yourstore.com/cancel",
"ipnUrl": "https://yourstore.com/webhooks/payerfox",
"tags": [
"subscription"
],
"meta": {
"userId": "u_8812",
"plan": "pro"
}
}'Response
{
"success": true,
"data": {
"id": "7f1c2e9a-0b3d-4c5e-9f10-2a3b4c5d6e7f",
"number": 1042,
"merchant_order_id": "ORDER-1001",
"external_order_id": null,
"gateway": null,
"website_id": "3d6f0a12-8c4b-4e1a-9b77-51c2d0e4f9aa",
"amount": "499.00",
"currency": "INR",
"order_amount": "499.00",
"order_currency": "INR",
"charge_amount": null,
"charge_currency": null,
"status": "pending",
"description": "Pro plan — 1 month",
"tags": [
"subscription"
],
"source": "website",
"checkout_url": "https://pay.example.com/checkout/q3k9x2m7ab",
"transaction_id": null,
"paid_at": null,
"expires_at": "2026-10-07T10:30:00.000Z",
"created_at": "2026-10-07T10:00:00.000Z",
"customer_name": "Asha Verma",
"customer_email": "asha@example.com",
"customer_phone": "+919800000000",
"order_items": [
{
"name": "Pro plan — 1 month",
"quantity": 1,
"unit_price": "499.00",
"sku": "PRO-1M",
"currency": null
}
],
"meta": {
"userId": "u_8812",
"plan": "pro"
}
}
}