RazPay API v1.0
API Reference
The RazPay API is a REST API over HTTPS. Requests and responses are JSON (UTF-8) and every request is authenticated with an API key of your merchant account. Times are UTC in ISO 8601.
https://www.raz-pay.com/api/v1
Introduction
Payments always take place on the RazPay hosted payment page. You create a Checkout Session, a Payment Link or an invoice with the API and send your customer to its URL. Card details are entered on the payment processor's page and never reach your server or RazPay; there is no API that accepts card numbers directly.
Amounts are integers in the minor unit (1/100) of your account currency: 250.00 is written 25000. The minimum amount per payment is 1.00 and the maximum amount per payment is 100,000.00 (in your account currency). Both limits are set by RazPay, and the maximum of your account may differ under your contract. Amounts outside the limits are rejected with 422 validation_failed.
Test keys work only on the test environment (https://www.raz-pay.com/staging/api/v1), and live keys only in production (https://www.raz-pay.com/api/v1). The test environment uses the same API, so you can build and test your integration before you go live.
Send request bodies as a JSON object with Content-Type: application/json; a body that cannot be read returns 400 invalid_json. Text fields must not contain control characters (descriptions, notes, reasons and metadata values may contain line breaks and tabs), and leading and trailing spaces are removed.
Typical integration
- Create a Checkout Session on your server (
POST /checkout-sessions) with the item, amount, your order number inclient_reference_id, andsuccess_url/cancel_url. - Redirect the customer to the session
url. The customer enters their details and pays on the payment processor's page. - Receive the
payment.succeededwebhook, verify its signature, and fulfil the order. The redirect tosuccess_urlis a convenience only. - Track the sale with the Transactions API and your monthly payouts with the Settlements API.
curl -X POST https://www.raz-pay.com/api/v1/checkout-sessions \
-H "Authorization: Bearer rz_live_…" \
-H "Idempotency-Key: order-1001-checkout-session" \
-H "Content-Type: application/json" \
-d '{
"name": "Premium plan (1 month)",
"amount_minor": 2500,
"quantity": 1,
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"success_url": "https://shop.example.com/thanks?session={CHECKOUT_SESSION_ID}",
"cancel_url": "https://shop.example.com/cart",
"customer": {
"email": "buyer@example.com",
"lock_email": true
},
"locale": "en"
}'Authentication
Send your API key as a Bearer token in the Authorization header. Keys start with rz_live_ in production and rz_test_ on the test environment; a key of the other environment is rejected with 401 unauthorized.
The owner of the merchant account creates keys in the Merchant Console (API keys). A key is shown only once, when it is created; RazPay stores only its hash. You can have up to 10 active keys and revoke a key at any time.
Each key has scopes. A request that needs a scope the key does not have returns 403 insufficient_scope. Give each system only the scopes it needs.
Keep keys on your server. Never put them in a web page, a mobile app or a public repository.
| Scope | Allows |
|---|---|
payments:read | Retrieve and list payments |
payment_links:read | Retrieve and list Payment Links |
payment_links:write | Create and deactivate Payment Links |
products:write | Create products |
invoices:write | Create and issue invoices |
refunds:write | Request cancellations and direct refunds |
transactions:read | Retrieve and list transactions |
vouchers:read | Retrieve vouchers |
settlements:read | List settlements |
checkout_sessions:read | Retrieve and list Checkout Sessions |
checkout_sessions:write | Create and expire Checkout Sessions |
products:read | Retrieve and list products |
invoices:read | Retrieve and list invoices |
refunds:read | Retrieve and list direct refunds |
events:read | Retrieve and list events |
curl https://www.raz-pay.com/api/v1/payments?limit=3 \
-H "Authorization: Bearer rz_live_…"Errors
RazPay uses HTTP status codes: 2xx success, 4xx a problem with the request, 5xx a problem on RazPay's side (retry later). The body of every error has error.code, error.message, error.fields (field name → messages, for validation_failed) and request_id.
Messages are in English by default. Send Accept-Language: ja to get message and fields in Japanese. code is the same in every language, so branch on code, not on message. Include request_id when you contact support.
| Status | Meaning |
|---|---|
200 | OK |
201 | Created |
202 | Accepted (the request is processed afterwards) |
400 | The request is malformed (e.g. a missing Idempotency-Key, or a body that is not a JSON object) |
401 | No valid API key |
403 | The key lacks a scope, or the account cannot do this now |
404 | The object or endpoint does not exist (or belongs to another merchant) |
405 | The method is not allowed for the endpoint (the `Allow` header lists the allowed methods) |
409 | Conflicts with the current state of the object or with an earlier request |
422 | Some fields are invalid |
429 | Too many requests |
500 | Internal error (retry later) |
| error.code | Meaning |
|---|---|
unauthorized | No API key, an invalid or revoked key, or a key of the other environment. |
insufficient_scope | The key does not have the scope of the endpoint. |
not_found | The object or endpoint does not exist, or belongs to another merchant. |
validation_failed | Some fields are invalid. See error.fields. |
invalid_json | The request body is not valid JSON or not a JSON object. |
idempotency_key_required | A POST without a valid Idempotency-Key header. |
idempotency_conflict | The Idempotency-Key was used with a different request body. |
request_in_progress | A request with the same Idempotency-Key is still being processed. |
rate_limited | Too many requests. Wait for Retry-After seconds. |
not_refundable | The payment cannot be cancelled or refunded in its current state. |
cancellation_period_passed | The payment processor's cancellation period has passed. |
partial_refund_not_supported | Partial cancellation is not supported for this payment. |
amount_invalid | The refund amount is larger than the remaining refundable amount. |
payments_not_enabled | The account cannot accept payments yet. |
merchant_suspended | The account is suspended and cannot accept new payments. |
merchant_closed | The account is closed and cannot accept new payments. |
merchant_unavailable | The merchant account is not available. |
checkout_session_not_open | The Checkout Session is already complete or expired. |
checkout_session_in_progress | A payment for the Checkout Session is being processed. |
payment_link_not_deactivatable | Links of product pages and invoices cannot be deactivated. |
method_not_allowed | The HTTP method is not allowed for the endpoint. |
internal_error | An error on RazPay's side. Retry later; contact support with the request_id if it continues. |
{
"error": {
"code": "validation_failed",
"message": "Some fields are invalid.",
"fields": {
"amount_minor": [
"The amount minor field must be at least 100."
]
}
},
"request_id": "01JBZ6X0F2H4K6M8P0R2T4W6Y8"
}Pagination
List endpoints return {"object": "list", "data": [...], "has_more": true, "url": "/v1/payments"}, newest first. limit is 1-100 (default 10; settlements 25).
For the next (older) page pass starting_after = the id of the last object of the current page. For the previous (newer) page pass ending_before = the id of the first object. Do not send both. has_more tells you whether there are more objects in the direction you paginate.
Filter by creation time with created[gte], created[gt], created[lte] and created[lt] (Unix seconds, or ISO 8601; UTC when no offset is given), plus the filters listed on each endpoint. Each query parameter takes one value; an array such as status[]=open returns 422 validation_failed.
curl "https://www.raz-pay.com/api/v1/payments?limit=50&status=psp_success&created[gte]=2026-11-01T00:00:00Z&starting_after=01jbz6x0d3k8h2m5n7p9q4r6s8" \
-H "Authorization: Bearer rz_live_…"Idempotency
Every POST requires an Idempotency-Key header: 8-100 characters of letters, digits and - _ : .. Without it the request is rejected with 400 idempotency_key_required.
Use one key per operation, for example your order number. If a request times out, send it again with the same key and the same body: you get the original response (with the header Idempotent-Replayed: true) and nothing is created twice. Error responses (4xx) are replayed too; 5xx responses are not stored, so you can retry them with the same key.
Sending the same key with a different body, or for another object (for example to expire a different Checkout Session), returns 409 idempotency_conflict; sending it while the first request is still running returns 409 request_in_progress. Keys are unique per merchant and endpoint and are kept for 7 days.
curl -X POST https://www.raz-pay.com/api/v1/payment-links \
-H "Authorization: Bearer rz_live_…" \
-H "Idempotency-Key: order-1001-link" \
-H "Content-Type: application/json" \
-d '{"name":"Consulting (1 hour)","amount_minor":25000}'
# Retried with the same key and body
HTTP/1.1 201 Created
Idempotent-Replayed: trueMetadata
metadata is up to 20 key-value pairs of your own. Keys are 1-40 characters (letters, digits, _ . -); values are strings up to 500 characters (numbers are converted to strings; null or an empty string removes the key). It is returned as an object ({} when empty).
client_reference_id is your own reference, for example an order number (up to 200 characters). You can filter Checkout Sessions and payments by it.
Set both on a Checkout Session or a Payment Link: they are copied to its payments and returned on payments, transactions, refunds and their webhooks. Do not put personal data or secrets in them.
{
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42",
"plan": "premium"
}
}Webhooks & signatures
Webhooks notify your server of events such as payment.succeeded. The owner of the merchant account registers endpoints in the Merchant Console (API keys): up to 5 endpoints, each an https:// URL (port 443 or 8443) that is reachable from the internet, with the event types it receives. The signing secret (whsec_…) is shown once, when the endpoint is created or the secret is rotated.
RazPay sends a POST with a JSON body and these headers:
| Header | Description |
|---|---|
X-RazPay-Event-Id | The event id (evt_…). The same on every retry of the event. |
X-RazPay-Timestamp | Unix time (seconds) when this delivery attempt was signed. |
X-RazPay-Signature | v1= followed by the hex HMAC-SHA256 of the signed payload, computed with your signing secret. |
Content-Type | application/json |
User-Agent | RazPay-Webhooks/1.0 |
Verify the signature
- Read the raw request body exactly as received (before any JSON parsing).
- Build the signed payload: the value of
X-RazPay-Timestamp, a period (.), and the raw body. - Compute HMAC-SHA256 of the signed payload with your endpoint's signing secret (the whole
whsec_…string) as the key, hex-encoded in lowercase, and prefix it withv1=. - Compare it with
X-RazPay-Signatureusing a constant-time comparison. Reject the request if they differ. - Reject the request if the timestamp is more than 5 minutes away from your server time (protection against replays).
- Respond with any 2xx status within 10 seconds, then process the event. Ignore event ids you have already processed.
Delivery and retries
- A 2xx response is a success. On a timeout, a connection error,
429or5xx, RazPay retries after about 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours and 24 hours. Other 4xx responses are not retried; you can resend a delivery from the Merchant Console. - Redirects are not followed. Requests time out after 10 seconds.
- Delivery order is not guaranteed and an event can be delivered more than once. Use
resource_version: ignore an event whoseresource_versionis lower than one you have already processed for the sameresource_id. - The Merchant Console can send a test event with type
pingto an endpoint. Every other event is also available from the Events API.
signed_payload = X-RazPay-Timestamp + "." + raw_body
X-RazPay-Signature = "v1=" + hex(HMAC_SHA256(key = whsec_…, signed_payload))$secret = getenv('RAZPAY_WEBHOOK_SECRET'); // whsec_…
$body = file_get_contents('php://input'); // raw body
$ts = $_SERVER['HTTP_X_RAZPAY_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_RAZPAY_SIGNATURE'] ?? '';
$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!ctype_digit($ts) || !hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {
http_response_code(400);
exit;
}
$event = json_decode($body, true);
// skip $event['id'] if already processed; compare resource_version
http_response_code(200);const crypto = require('crypto');
app.post('/webhooks/razpay', express.raw({ type: 'application/json' }), (req, res) => {
const ts = req.get('X-RazPay-Timestamp') || '';
const sig = req.get('X-RazPay-Signature') || '';
const expected = 'v1=' + crypto.createHmac('sha256', process.env.RAZPAY_WEBHOOK_SECRET)
.update(ts + '.').update(req.body).digest('hex');
const ok = sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
if (!ok || !/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
return res.sendStatus(400);
}
const event = JSON.parse(req.body.toString('utf8'));
res.sendStatus(200);
});{
"id": "evt_01jbz6x0d5q7s9v1x3z5b7d9f1",
"type": "payment.succeeded",
"occurred_at": "2026-11-06T09:31:12.345Z",
"environment": "test",
"resource_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"resource_version": 1,
"data": {
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "psp_success",
"amount_minor": 2500,
"currency": "USD",
"fee_minor": 125,
"net_minor": 2375,
"item_name": "Premium plan (1 month)",
"quantity": 1,
"payment_link_id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"invoice_id": null,
"created_at": "2026-11-06T09:30:00Z",
"succeeded_at": "2026-11-06T09:31:12Z",
"object": "payment",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
}
}Event types
Choose the event types for each endpoint in the Merchant Console. data is the object shown; resource_id is its id.
| Event type | data | Description |
|---|---|---|
payment.succeeded | Payment | A payment succeeded. Fulfil the order after this event. |
payment.failed | Payment | A payment failed or was declined. |
transaction.pending_sale | Transaction | A transaction was created for a successful payment (not yet eligible for settlement). |
transaction.fulfillment | Transaction | The order was marked as delivered. |
transaction.actual_sale | Transaction | The transaction became eligible for settlement (receipt confirmed by the customer, automatically after the set time, or by RazPay). |
transaction.on_hold | Transaction | The transaction was put on hold for review. |
transaction.hold_released | Transaction | The hold was released. |
refund.requested | Transaction / Refund event data | A cancellation or a direct refund was requested. |
refund.recorded | Refund event data | You recorded the direct refund to the customer. |
refund.rejected | Transaction | The cancellation request was declined. |
refund.completed | Transaction / Refund event data | The cancellation or the direct refund was completed. |
refund.withdrawn | Refund event data | The direct refund request was withdrawn. |
dispute.opened | Transaction | The customer reported a problem with the order; the transaction is on hold. |
dispute.resolved | Transaction | The reported problem was resolved and the hold released. |
settlement.created | Settlement | A monthly settlement was created (draft). |
settlement.confirmed | Settlement | The settlement was confirmed, with the USDC amount and rate fixed. |
settlement.reverted | Settlement | The confirmation was withdrawn before payout and the settlement returned to draft (it will be confirmed again). |
settlement.paid | Settlement | The payout was sent (USDC on Polygon; txid is set). |
checkout_session.completed | Checkout Session | The payment of a Checkout Session succeeded. |
checkout_session.expired | Checkout Session | A Checkout Session expired (by time or by the API). |
Rate limits
Each API key can make up to 120 requests per minute. Every authenticated response carries X-RateLimit-Limit (120) and X-RateLimit-Remaining.
Over the limit the API returns 429 rate_limited with Retry-After (seconds to wait). Wait that long and retry; for bulk work, spread requests out and use list filters instead of retrieving objects one by one.
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
{"error":{"code":"rate_limited","message":"Too many requests. Please retry later.","fields":{}},"request_id":"…"}Checkout Sessions
A Checkout Session is a single-use hosted payment page for one order. Create it on your server, redirect the customer to its url, and fulfil the order after the payment.succeeded or checkout_session.completed webhook. This is the recommended integration for websites.
Create a Checkout Session
POST/v1/checkout-sessions
Creates a single-use hosted payment page. Redirect the customer to url. Give product_id (+ quantity) or name + amount_minor.
Required scope: checkout_sessions:write
Parameters
-
Idempotency-Keystringheaderrequiredpattern^[A-Za-z0-9_\-:.]{8,100}$
Request body application/json
-
product_idstringProduct id (26 chars) -
namestringItem name shown on the payment page (required without product_id)max length100 -
descriptionstringmax length1000 -
amount_minorintegerUnit price in minor units (required without product_id). The total (× quantity) must be within your minimum and maximum per paymentmin100max99999999 -
quantityintegermin1max999default1 -
currencystringYour account currency. Other values are rejectedone ofMYR, USD, AED -
display_currencystringReference display onlyone ofMYR, USD, AED, JPY -
client_reference_idstringYour own reference (e.g. order number). Filter with GET /checkout-sessions?client_reference_id= and GET /payments?client_reference_id=max length200 -
metadataMetadataUp to 20 pairs. Keys: 1-40 characters [A-Za-z0-9_.-]. Values: strings up to 500 characters (numbers are converted to strings; null or empty removes the key). Returned as an object ({} when empty)max pairs20keys^[A-Za-z0-9_.\-]{1,40}$ -
success_urlstring (uri)Where the customer's browser goes after a successful payment. https only in production (http is accepted on the test environment); javascript:, data: and other schemes are rejected. {CHECKOUT_SESSION_ID} is replaced with the session id. Without it, the customer stays on the RazPay order pagemax length2000 -
cancel_urlstring (uri)Target of the "Cancel and return to the shop" link on the payment page (also shown when the session can no longer be used). Same rules as success_urlmax length2000 -
customerobjectPrefill the payment form. The customer can change name and phone. These values are never returned by the API or webhooks -
customer.namestringmax length100 -
customer.emailstring (email)max length150 -
customer.phonestringInternational format recommended (+819012345678) -
customer.lock_emailbooleantrue = the email cannot be changed and only this email can pay (requires customer.email)defaultfalse -
localestringLanguage of the payment page (default English; the customer can switch)one ofja, en -
expires_atinteger | string (date-time)30 minutes to 7 days from now. Default: 24 hours -
auto_eligible_hoursintegermin0max168default0
Returns
Returns the Checkout Session object.
curl -X POST https://www.raz-pay.com/api/v1/checkout-sessions \
-H "Authorization: Bearer rz_live_…" \
-H "Idempotency-Key: order-1001-checkout-session" \
-H "Content-Type: application/json" \
-d '{
"name": "Premium plan (1 month)",
"amount_minor": 2500,
"quantity": 1,
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"success_url": "https://shop.example.com/thanks?session={CHECKOUT_SESSION_ID}",
"cancel_url": "https://shop.example.com/cart",
"customer": {
"email": "buyer@example.com",
"lock_email": true
},
"locale": "en"
}'{
"id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"object": "checkout_session",
"url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"status": "open",
"payment_status": "unpaid",
"payment_id": null,
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"product_id": null,
"quantity": 1,
"amount_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"success_url": "https://shop.example.com/thanks?session={CHECKOUT_SESSION_ID}",
"cancel_url": "https://shop.example.com/cart",
"customer_prefilled": false,
"lock_email": false,
"locale": "en",
"auto_eligible_hours": 0,
"expires_at": "2026-11-07T09:30:00Z",
"completed_at": null,
"expired_at": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}Retrieve a Checkout Session
GET/v1/checkout-sessions/{id}
Required scope: checkout_sessions:read
Parameters
-
idstringpathrequiredpattern^[0-9a-z]{26}$
Returns
Returns the Checkout Session object.
- 200 OK
- 404 Error — Error
curl https://www.raz-pay.com/api/v1/checkout-sessions/01jbz6x0d3k8h2m5n7p9q4cs01 \
-H "Authorization: Bearer rz_live_…"{
"id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"object": "checkout_session",
"url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"status": "open",
"payment_status": "unpaid",
"payment_id": null,
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"product_id": null,
"quantity": 1,
"amount_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"success_url": "https://shop.example.com/thanks?session={CHECKOUT_SESSION_ID}",
"cancel_url": "https://shop.example.com/cart",
"customer_prefilled": false,
"lock_email": false,
"locale": "en",
"auto_eligible_hours": 0,
"expires_at": "2026-11-07T09:30:00Z",
"completed_at": null,
"expired_at": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}List Checkout Sessions
GET/v1/checkout-sessions
Required scope: checkout_sessions:read
Parameters
-
limitintegerquerymin1max100default10 -
starting_afterstringqueryId of the last object of the current page; returns older objects -
ending_beforestringqueryId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectquerycreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringqueryone ofopen, complete, expired -
client_reference_idstringquery -
payment_idstringquery
Returns
Returns a list of Checkout Session objects.
- 200 OK
- 422 Error — Error
curl "https://www.raz-pay.com/api/v1/checkout-sessions?limit=3" \
-H "Authorization: Bearer rz_live_…"{
"object": "list",
"data": [
{
"id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"object": "checkout_session",
"url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"status": "open",
"payment_status": "unpaid",
"payment_id": null,
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"product_id": null,
"quantity": 1,
"amount_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"success_url": "https://shop.example.com/thanks?session={CHECKOUT_SESSION_ID}",
"cancel_url": "https://shop.example.com/cart",
"customer_prefilled": false,
"lock_email": false,
"locale": "en",
"auto_eligible_hours": 0,
"expires_at": "2026-11-07T09:30:00Z",
"completed_at": null,
"expired_at": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}
],
"has_more": false,
"url": "/v1/checkout-sessions"
}Expire a Checkout Session
POST/v1/checkout-sessions/{id}/expire
Stops accepting payments on an open session (status becomes expired, url becomes null; webhook checkout_session.expired). 409 checkout_session_not_open if it is already complete or expired; 409 checkout_session_in_progress while the payment processor is processing a payment for it.
Required scope: checkout_sessions:write
Parameters
-
idstringpathrequiredpattern^[0-9a-z]{26}$ -
Idempotency-Keystringheaderrequiredpattern^[A-Za-z0-9_\-:.]{8,100}$
Returns
Returns the Checkout Session object.
curl -X POST https://www.raz-pay.com/api/v1/checkout-sessions/01jbz6x0d3k8h2m5n7p9q4cs01/expire \
-H "Authorization: Bearer rz_live_…" \
-H "Idempotency-Key: order-1001-checkout-session"{
"id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"object": "checkout_session",
"url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"status": "open",
"payment_status": "unpaid",
"payment_id": null,
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"product_id": null,
"quantity": 1,
"amount_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"success_url": "https://shop.example.com/thanks?session={CHECKOUT_SESSION_ID}",
"cancel_url": "https://shop.example.com/cart",
"customer_prefilled": false,
"lock_email": false,
"locale": "en",
"auto_eligible_hours": 0,
"expires_at": "2026-11-07T09:30:00Z",
"completed_at": null,
"expired_at": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}Payment Links
A Payment Link is a reusable (or limited-use) URL of the RazPay payment page with a fixed item and amount. Send it by email, chat or QR code.
Create a Payment Link
POST/v1/payment-links
Required scope: payment_links:write
Parameters
-
Idempotency-Keystringheaderrequiredpattern^[A-Za-z0-9_\-:.]{8,100}$
Request body application/json
Give product_id (+ quantity) or name + amount_minor.
-
product_idstringProduct id (26 chars) -
namestringmax length100 -
descriptionstringmax length1000 -
amount_minorintegerUnit price in minor units (1/100 of your account currency) when no product_idmin100max99999999 -
quantityintegermin1max999default1 -
currencystringYour account currency (set by the payment processor of your account). Other values are rejectedone ofMYR, USD, AED -
display_currencystringReference display only; customers pay in your account currencyone ofMYR, USD, AED, JPY -
expires_atstring (date-time) -
max_usesinteger1 = single usemin1 -
auto_eligible_hoursintegerHours after payment until the transaction becomes eligible for settlement without the buyer's receipt confirmation. 0 = immediately (the buyer can confirm receipt on the order page right after paying)min0max168default0 -
client_reference_idstringYour own reference (e.g. order number). Copied to the payments of this linkmax length200 -
metadataMetadataUp to 20 pairs. Keys: 1-40 characters [A-Za-z0-9_.-]. Values: strings up to 500 characters (numbers are converted to strings; null or empty removes the key). Returned as an object ({} when empty)max pairs20keys^[A-Za-z0-9_.\-]{1,40}$
Returns
Returns the Payment Link object.
curl -X POST https://www.raz-pay.com/api/v1/payment-links \
-H "Authorization: Bearer rz_live_…" \
-H "Idempotency-Key: order-1001-payment-link" \
-H "Content-Type: application/json" \
-d '{
"name": "Consulting (1 hour)",
"amount_minor": 25000,
"quantity": 1,
"max_uses": 1,
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
}'{
"id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"object": "payment_link",
"url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"amount_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"quantity": 1,
"product_id": null,
"status": "active",
"usable": true,
"state": "ok",
"max_uses": 1,
"uses_count": 0,
"auto_eligible_hours": 0,
"expires_at": null,
"created_at": "2026-11-06T09:30:00Z",
"purpose": "link",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"livemode": false
}Retrieve a Payment Link
GET/v1/payment-links/{id}
Required scope: payment_links:read
Parameters
-
idstringpathrequiredpattern^[0-9a-z]{26}$
Returns
Returns the Payment Link object.
- 200 OK
- 404 Error — Error
curl https://www.raz-pay.com/api/v1/payment-links/01jbz5w8y0a2c4e6g8j0k2pl01 \
-H "Authorization: Bearer rz_live_…"{
"id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"object": "payment_link",
"url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"amount_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"quantity": 1,
"product_id": null,
"status": "active",
"usable": true,
"state": "ok",
"max_uses": 1,
"uses_count": 0,
"auto_eligible_hours": 0,
"expires_at": null,
"created_at": "2026-11-06T09:30:00Z",
"purpose": "link",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"livemode": false
}List Payment Links
GET/v1/payment-links
Links of every kind (purpose link, email, product, invoice). Links of Checkout Sessions are not included.
Required scope: payment_links:read
Parameters
-
limitintegerquerymin1max100default10 -
starting_afterstringqueryId of the last object of the current page; returns older objects -
ending_beforestringqueryId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectquerycreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringqueryone ofactive, disabled
Returns
Returns a list of Payment Link objects.
- 200 OK
- 422 Error — Error
curl "https://www.raz-pay.com/api/v1/payment-links?limit=3" \
-H "Authorization: Bearer rz_live_…"{
"object": "list",
"data": [
{
"id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"object": "payment_link",
"url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"amount_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"quantity": 1,
"product_id": null,
"status": "active",
"usable": true,
"state": "ok",
"max_uses": 1,
"uses_count": 0,
"auto_eligible_hours": 0,
"expires_at": null,
"created_at": "2026-11-06T09:30:00Z",
"purpose": "link",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"livemode": false
}
],
"has_more": false,
"url": "/v1/payment-links"
}Deactivate a Payment Link
POST/v1/payment-links/{id}/deactivate
The link can no longer be used. Repeating the call returns the same link. Only links of purpose link and email; links of product pages and invoices return 409 payment_link_not_deactivatable.
Required scope: payment_links:write
Parameters
-
idstringpathrequiredpattern^[0-9a-z]{26}$ -
Idempotency-Keystringheaderrequiredpattern^[A-Za-z0-9_\-:.]{8,100}$
Returns
Returns the Payment Link object.
curl -X POST https://www.raz-pay.com/api/v1/payment-links/01jbz5w8y0a2c4e6g8j0k2pl01/deactivate \
-H "Authorization: Bearer rz_live_…" \
-H "Idempotency-Key: order-1001-payment-link"{
"id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"object": "payment_link",
"url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"amount_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"quantity": 1,
"product_id": null,
"status": "active",
"usable": true,
"state": "ok",
"max_uses": 1,
"uses_count": 0,
"auto_eligible_hours": 0,
"expires_at": null,
"created_at": "2026-11-06T09:30:00Z",
"purpose": "link",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"livemode": false
}Products
Products are items with a fixed price. Use product_id when you create a Checkout Session or a Payment Link.
Create a product
POST/v1/products
Required scope: products:write
Parameters
-
Idempotency-Keystringheaderrequiredpattern^[A-Za-z0-9_\-:.]{8,100}$
Request body application/json
-
namestringrequiredmax length100 -
descriptionstringmax length1000 -
kindstringone ofservice, goods, otherdefaultservice -
price_minorintegerrequiredmin100max99999999 -
currencystringYour account currency (set by the payment processor of your account). Other values are rejectedone ofMYR, USD, AED -
display_currencystringone ofMYR, USD, AED, JPY
Returns
Returns the Product object.
curl -X POST https://www.raz-pay.com/api/v1/products \
-H "Authorization: Bearer rz_live_…" \
-H "Idempotency-Key: order-1001-product" \
-H "Content-Type: application/json" \
-d '{
"name": "Premium plan (1 month)",
"price_minor": 2500,
"kind": "service"
}'{
"id": "01jbz4v6x8z0b2d4f6h8j0pr01",
"object": "product",
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"kind": "service",
"price_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"active": true,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}Retrieve a product
GET/v1/products/{id}
Required scope: products:read
Parameters
-
idstringpathrequiredpattern^[0-9a-z]{26}$
Returns
Returns the Product object.
- 200 OK
- 404 Error — Error
curl https://www.raz-pay.com/api/v1/products/01jbz4v6x8z0b2d4f6h8j0pr01 \
-H "Authorization: Bearer rz_live_…"{
"id": "01jbz4v6x8z0b2d4f6h8j0pr01",
"object": "product",
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"kind": "service",
"price_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"active": true,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}List products
GET/v1/products
Required scope: products:read
Parameters
-
limitintegerquerymin1max100default10 -
starting_afterstringqueryId of the last object of the current page; returns older objects -
ending_beforestringqueryId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectquerycreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
activebooleanquery
Returns
Returns a list of Product objects.
- 200 OK
- 422 Error — Error
curl "https://www.raz-pay.com/api/v1/products?limit=3" \
-H "Authorization: Bearer rz_live_…"{
"object": "list",
"data": [
{
"id": "01jbz4v6x8z0b2d4f6h8j0pr01",
"object": "product",
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"kind": "service",
"price_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"active": true,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}
],
"has_more": false,
"url": "/v1/products"
}Invoices
Invoices have line items, tax and a due date. An issued invoice has a pay_url; when bill_to_email is set, RazPay emails the invoice with the PDF attached.
Create (and by default issue) an invoice
POST/v1/invoices
Required scope: invoices:write
Parameters
-
Idempotency-Keystringheaderrequiredpattern^[A-Za-z0-9_\-:.]{8,100}$
Request body application/json
Send either items (line items; subtotal, tax and total are calculated) or amount_minor (one line, tax included).
-
bill_tostringrequiredmax length100 -
bill_to_emailstring (email)If set, the invoice is emailed when issued, with the PDF attached and the payment link -
bill_to_addressstringmax length500 -
descriptionstringmax length150 -
amount_minorintegerTax included. Required when items is not sentmin100max99999999 -
itemsarray of objectmin items1max items20 -
items[].descriptionstringrequiredmax length191 -
items[].quantityintegerrequiredmin1max100000 -
items[].unit_price_minorintegerrequiredmin0 -
tax_rate_bpintegerTax rate in basis points (600 = 6%). Tax = subtotal × rate, rounded to the nearest minor unit (1/100)min0max10000default0 -
currencystringYour account currency (set by the payment processor of your account). Other values are rejectedone ofMYR, USD, AED -
issue_datestring (date) -
due_datestring (date)required -
notesstringmax length1000 -
auto_eligible_hoursintegerHours after payment until the transaction becomes eligible for settlement without the buyer's receipt confirmation. 0 = immediately (the buyer can confirm receipt on the order page right after paying)min0max168default0 -
issuebooleandefaulttrue -
localestringone ofen, ja
Returns
Returns the Invoice object.
curl -X POST https://www.raz-pay.com/api/v1/invoices \
-H "Authorization: Bearer rz_live_…" \
-H "Idempotency-Key: order-1001-invoice" \
-H "Content-Type: application/json" \
-d '{
"bill_to": "Sample Trading Ltd.",
"bill_to_email": "billing@example.com",
"items": [
{
"description": "Consulting (1 hour)",
"quantity": 2,
"unit_price_minor": 25000
}
],
"due_date": "2026-11-30",
"locale": "en"
}'{
"id": "01jbz3t5v7x9z1b3d5f7h9in01",
"object": "invoice",
"invoice_number": "INV-202611-00001",
"status": "issued",
"bill_to": "Sample Trading Ltd.",
"description": "Monthly subscription",
"items": [
{
"description": "Monthly subscription",
"quantity": 1,
"unit_price_minor": 2500,
"amount_minor": 2500
}
],
"subtotal_minor": 2500,
"tax_rate_bp": 0,
"tax_minor": 0,
"amount_minor": 2500,
"currency": "USD",
"locale": "en",
"issue_date": "2026-11-06",
"due_date": "2026-11-30",
"auto_eligible_hours": 0,
"pay_url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"payment_link_id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"issued_at": "2026-11-06T09:30:00Z",
"paid_at": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}Retrieve an invoice
GET/v1/invoices/{id}
Required scope: invoices:read
Parameters
-
idstringpathrequiredpattern^[0-9a-z]{26}$
Returns
Returns the Invoice object.
- 200 OK
- 404 Error — Error
curl https://www.raz-pay.com/api/v1/invoices/01jbz3t5v7x9z1b3d5f7h9in01 \
-H "Authorization: Bearer rz_live_…"{
"id": "01jbz3t5v7x9z1b3d5f7h9in01",
"object": "invoice",
"invoice_number": "INV-202611-00001",
"status": "issued",
"bill_to": "Sample Trading Ltd.",
"description": "Monthly subscription",
"items": [
{
"description": "Monthly subscription",
"quantity": 1,
"unit_price_minor": 2500,
"amount_minor": 2500
}
],
"subtotal_minor": 2500,
"tax_rate_bp": 0,
"tax_minor": 0,
"amount_minor": 2500,
"currency": "USD",
"locale": "en",
"issue_date": "2026-11-06",
"due_date": "2026-11-30",
"auto_eligible_hours": 0,
"pay_url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"payment_link_id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"issued_at": "2026-11-06T09:30:00Z",
"paid_at": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}List invoices
GET/v1/invoices
Required scope: invoices:read
Parameters
-
limitintegerquerymin1max100default10 -
starting_afterstringqueryId of the last object of the current page; returns older objects -
ending_beforestringqueryId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectquerycreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringqueryone ofdraft, issued, paid, void, refunded
Returns
Returns a list of Invoice objects.
- 200 OK
- 422 Error — Error
curl "https://www.raz-pay.com/api/v1/invoices?limit=3" \
-H "Authorization: Bearer rz_live_…"{
"object": "list",
"data": [
{
"id": "01jbz3t5v7x9z1b3d5f7h9in01",
"object": "invoice",
"invoice_number": "INV-202611-00001",
"status": "issued",
"bill_to": "Sample Trading Ltd.",
"description": "Monthly subscription",
"items": [
{
"description": "Monthly subscription",
"quantity": 1,
"unit_price_minor": 2500,
"amount_minor": 2500
}
],
"subtotal_minor": 2500,
"tax_rate_bp": 0,
"tax_minor": 0,
"amount_minor": 2500,
"currency": "USD",
"locale": "en",
"issue_date": "2026-11-06",
"due_date": "2026-11-30",
"auto_eligible_hours": 0,
"pay_url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"payment_link_id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"issued_at": "2026-11-06T09:30:00Z",
"paid_at": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}
],
"has_more": false,
"url": "/v1/invoices"
}Payments
A payment is one attempt by a customer to pay a Checkout Session, Payment Link or invoice. Only payments whose status is psp_success become transactions.
Retrieve a payment
GET/v1/payments/{id}
Required scope: payments:read
Parameters
-
idstringpathrequiredpattern^[0-9a-z]{26}$
Returns
Returns the Payment object.
- 200 OK
- 404 Error — Error
Response fields
-
idstring -
order_idstring -
statusstringone ofcreated, payment_pending, psp_processing, psp_success, failed, cancelled -
amount_minorinteger -
currencystring -
fee_minorinteger -
net_minorinteger -
item_namestring -
quantityinteger -
payment_link_idstring | null -
invoice_idstring | null -
created_atstring (date-time) -
succeeded_atstring (date-time) | null -
objectstringalways"payment" -
livemodeboolean -
checkout_session_idstring | nullCheckout Session the payment was made from -
client_reference_idstring | nullCopied from the Checkout Session or Payment Link -
metadataMetadataUp to 20 pairs. Keys: 1-40 characters [A-Za-z0-9_.-]. Values: strings up to 500 characters (numbers are converted to strings; null or empty removes the key). Returned as an object ({} when empty)max pairs20keys^[A-Za-z0-9_.\-]{1,40}$ -
transactionTransaction | null
curl https://www.raz-pay.com/api/v1/payments/01jbz6x0d3k8h2m5n7p9q4r6s8 \
-H "Authorization: Bearer rz_live_…"{
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "psp_success",
"amount_minor": 2500,
"currency": "USD",
"fee_minor": 125,
"net_minor": 2375,
"item_name": "Premium plan (1 month)",
"quantity": 1,
"payment_link_id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"invoice_id": null,
"created_at": "2026-11-06T09:30:00Z",
"succeeded_at": "2026-11-06T09:31:12Z",
"object": "payment",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"transaction": {
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "pending_sale",
"settlement_status": "not_eligible",
"sale_status": "pending_sale",
"hold": null,
"refund_status": null,
"amount_minor": 2500,
"fee_minor": 125,
"net_minor": 2375,
"currency": "USD",
"pending_at": "2026-11-06T09:31:12Z",
"auto_eligible_at": "2026-11-06T09:31:12Z",
"fulfilled_at": null,
"actual_sale_at": null,
"cancelled_at": null,
"settlement_id": null,
"voucher_id": "01jbz6x0d3k8h2m5n7p9q4vc01",
"version": 2,
"object": "transaction",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
}
}List payments
GET/v1/payments
Required scope: payments:read
Parameters
-
limitintegerquerymin1max100default10 -
starting_afterstringqueryId of the last object of the current page; returns older objects -
ending_beforestringqueryId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectquerycreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringqueryone ofcreated, payment_pending, psp_processing, psp_success, failed, cancelled -
client_reference_idstringquery
Returns
Returns the object described below.
- 200 OK
- 422 Error — Error
Response fields
-
objectstringalways"list" -
dataarray of Payment -
data[].idstring -
data[].order_idstring -
data[].statusstringone ofcreated, payment_pending, psp_processing, psp_success, failed, cancelled -
data[].amount_minorinteger -
data[].currencystring -
data[].fee_minorinteger -
data[].net_minorinteger -
data[].item_namestring -
data[].quantityinteger -
data[].payment_link_idstring | null -
data[].invoice_idstring | null -
data[].created_atstring (date-time) -
data[].succeeded_atstring (date-time) | null -
data[].objectstringalways"payment" -
data[].livemodeboolean -
data[].checkout_session_idstring | nullCheckout Session the payment was made from -
data[].client_reference_idstring | nullCopied from the Checkout Session or Payment Link -
data[].metadataMetadataUp to 20 pairs. Keys: 1-40 characters [A-Za-z0-9_.-]. Values: strings up to 500 characters (numbers are converted to strings; null or empty removes the key). Returned as an object ({} when empty)max pairs20keys^[A-Za-z0-9_.\-]{1,40}$ -
data[].transactionTransaction | nullThe transaction of a successful payment (null otherwise), as in GET /payments/{id} -
has_morebooleantrue if there are more objects in the direction you paginate -
urlstring
curl "https://www.raz-pay.com/api/v1/payments?limit=3" \
-H "Authorization: Bearer rz_live_…"{
"object": "list",
"data": [
{
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "psp_success",
"amount_minor": 2500,
"currency": "USD",
"fee_minor": 125,
"net_minor": 2375,
"item_name": "Premium plan (1 month)",
"quantity": 1,
"payment_link_id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"invoice_id": null,
"created_at": "2026-11-06T09:30:00Z",
"succeeded_at": "2026-11-06T09:31:12Z",
"object": "payment",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"transaction": {
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "pending_sale",
"settlement_status": "not_eligible",
"sale_status": "pending_sale",
"hold": null,
"refund_status": null,
"amount_minor": 2500,
"fee_minor": 125,
"net_minor": 2375,
"currency": "USD",
"pending_at": "2026-11-06T09:31:12Z",
"auto_eligible_at": "2026-11-06T09:31:12Z",
"fulfilled_at": null,
"actual_sale_at": null,
"cancelled_at": null,
"settlement_id": null,
"voucher_id": "01jbz6x0d3k8h2m5n7p9q4vc01",
"version": 2,
"object": "transaction",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
}
}
],
"has_more": false,
"url": "/v1/payments"
}Transactions
A transaction is a successful payment as it moves towards settlement. Its id is the payment id.
Retrieve a transaction (id = payment id)
GET/v1/transactions/{id}
Required scope: transactions:read
Parameters
-
idstringpathrequiredpattern^[0-9a-z]{26}$
Returns
Returns the Transaction object.
- 200 OK
- 404 Error — Error
curl https://www.raz-pay.com/api/v1/transactions/01jbz6x0d3k8h2m5n7p9q4r6s8 \
-H "Authorization: Bearer rz_live_…"{
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "pending_sale",
"settlement_status": "not_eligible",
"sale_status": "pending_sale",
"hold": null,
"refund_status": null,
"amount_minor": 2500,
"fee_minor": 125,
"net_minor": 2375,
"currency": "USD",
"pending_at": "2026-11-06T09:31:12Z",
"auto_eligible_at": "2026-11-06T09:31:12Z",
"fulfilled_at": null,
"actual_sale_at": null,
"cancelled_at": null,
"settlement_id": null,
"voucher_id": "01jbz6x0d3k8h2m5n7p9q4vc01",
"version": 2,
"object": "transaction",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
}List transactions (successful payments)
GET/v1/transactions
The id of a transaction is the payment id; starting_after / ending_before also take payment ids.
Required scope: transactions:read
Parameters
-
limitintegerquerymin1max100default10 -
starting_afterstringqueryId of the last object of the current page; returns older objects -
ending_beforestringqueryId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectquerycreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringquerysale_statusone ofpending_sale, fulfillment, actual_sale, cancelled
Returns
Returns a list of Transaction objects.
- 200 OK
- 422 Error — Error
curl "https://www.raz-pay.com/api/v1/transactions?limit=3" \
-H "Authorization: Bearer rz_live_…"{
"object": "list",
"data": [
{
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "pending_sale",
"settlement_status": "not_eligible",
"sale_status": "pending_sale",
"hold": null,
"refund_status": null,
"amount_minor": 2500,
"fee_minor": 125,
"net_minor": 2375,
"currency": "USD",
"pending_at": "2026-11-06T09:31:12Z",
"auto_eligible_at": "2026-11-06T09:31:12Z",
"fulfilled_at": null,
"actual_sale_at": null,
"cancelled_at": null,
"settlement_id": null,
"voucher_id": "01jbz6x0d3k8h2m5n7p9q4vc01",
"version": 2,
"object": "transaction",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
}
],
"has_more": false,
"url": "/v1/transactions"
}Refunds
Request a cancellation or record a direct refund of a payment. What happens depends on the payment processor of the payment; see the endpoint description.
Request a cancellation or a direct refund of a payment
POST/v1/refunds
What happens depends on the payment processor of the payment. (1) Processor that can cancel payments: a cancellation request. It is accepted (202) and RazPay cancels the payment with the processor; refund.completed or refund.rejected is sent when done. Allowed within the processor's cancellation period (409 cancellation_period_passed after it). If the transaction is already included in a settlement, its payout amount is deducted from a later settlement. Partial cancellation is not supported. The 202 body has no id or type. (2) Processor that cannot cancel payments: a direct refund is created (type direct). The sale and settlement stay unchanged; the merchant refunds the customer directly and records it in the Merchant Console. Partial amounts are allowed (up to the remaining refundable amount, 422 amount_invalid otherwise). Webhooks: refund.requested, refund.recorded (the merchant recorded the refund), refund.completed, refund.withdrawn (the request was withdrawn). The 202 body is the refund (id, type, status, amount_minor, currency, reason, due_on, refunded_on, method, created_at) plus the transaction.
Required scope: refunds:write
Parameters
-
Idempotency-Keystringheaderrequiredpattern^[A-Za-z0-9_\-:.]{8,100}$
Request body application/json
-
payment_idstringrequired -
amount_minorintegerOptional. Cancellation: must equal the payment amount. Direct refund: 1 to the remaining refundable amount (default: all) -
reasonstringrequiredmax length1000
Returns
Returns the object described below.
Response fields
-
objectstringalways"refund" -
idstringDirect refund only: the refund ID (resource_id of refund.* webhooks for direct refunds). Absent for a cancellation request -
typestringDirect refund only. Absent for a cancellation requestone ofdirect -
payment_idstring -
statusstringAlways requested in this response. Later states of a direct refund (webhook data.refund.status): refunded, completed, cancelledone ofrequested -
amount_minorinteger -
currencystring -
reasonstring | nullDirect refund only -
due_onstring (date) | nullDirect refund only: planned refund date (Japan time), if set -
refunded_onstring (date) | nullDirect refund only: date the merchant refunded the customer; null until recorded -
methodstring | nullDirect refund only: how the merchant refunded; null until recordedone ofbank_transfer, crypto_wallet, cash, other, null -
created_atstring (date-time)Direct refund only -
livemodebooleanDirect refund only -
transactionTransaction
curl -X POST https://www.raz-pay.com/api/v1/refunds \
-H "Authorization: Bearer rz_live_…" \
-H "Idempotency-Key: refund-order-1001" \
-H "Content-Type: application/json" \
-d '{
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"reason": "Customer request"
}'{
"object": "refund",
"id": "01jbz7a2c4e6g8j0k2m4n6rf01",
"type": "direct",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"status": "requested",
"amount_minor": 2500,
"currency": "USD",
"reason": "Customer request",
"due_on": null,
"refunded_on": null,
"method": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false,
"transaction": {
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "pending_sale",
"settlement_status": "not_eligible",
"sale_status": "pending_sale",
"hold": null,
"refund_status": null,
"amount_minor": 2500,
"fee_minor": 125,
"net_minor": 2375,
"currency": "USD",
"pending_at": "2026-11-06T09:31:12Z",
"auto_eligible_at": "2026-11-06T09:31:12Z",
"fulfilled_at": null,
"actual_sale_at": null,
"cancelled_at": null,
"settlement_id": null,
"voucher_id": "01jbz6x0d3k8h2m5n7p9q4vc01",
"version": 2,
"object": "transaction",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
}
}Retrieve a direct refund
GET/v1/refunds/{id}
Required scope: refunds:read
Parameters
-
idstringpathrequiredpattern^[0-9a-z]{26}$
Returns
Returns the Refund object.
- 200 OK
- 404 Error — Error
curl https://www.raz-pay.com/api/v1/refunds/01jbz7a2c4e6g8j0k2m4n6rf01 \
-H "Authorization: Bearer rz_live_…"{
"object": "refund",
"id": "01jbz7a2c4e6g8j0k2m4n6rf01",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"type": "direct",
"status": "requested",
"amount_minor": 2500,
"currency": "USD",
"reason": "Customer request",
"due_on": null,
"refunded_on": null,
"method": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
}List direct refunds
GET/v1/refunds
Direct refunds (type direct). Cancellation requests of processors that can cancel are shown on the transaction (refund_status).
Required scope: refunds:read
Parameters
-
limitintegerquerymin1max100default10 -
starting_afterstringqueryId of the last object of the current page; returns older objects -
ending_beforestringqueryId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectquerycreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringqueryone ofrequested, refunded, completed, cancelled -
payment_idstringquery
Returns
Returns a list of Refund objects.
- 200 OK
- 422 Error — Error
curl "https://www.raz-pay.com/api/v1/refunds?limit=3" \
-H "Authorization: Bearer rz_live_…"{
"object": "list",
"data": [
{
"object": "refund",
"id": "01jbz7a2c4e6g8j0k2m4n6rf01",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"type": "direct",
"status": "requested",
"amount_minor": 2500,
"currency": "USD",
"reason": "Customer request",
"due_on": null,
"refunded_on": null,
"method": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
}
],
"has_more": false,
"url": "/v1/refunds"
}Vouchers
Every successful payment has a voucher (a public reference of the purchase).
Retrieve a voucher
GET/v1/vouchers/{id}
Required scope: vouchers:read
Parameters
-
idstringpathrequiredpattern^[0-9a-z]{26}$
Returns
Returns the Voucher object.
- 200 OK
- 404 Error — Error
curl https://www.raz-pay.com/api/v1/vouchers/01jbz6x0d3k8h2m5n7p9q4vc01 \
-H "Authorization: Bearer rz_live_…"{
"id": "01jbz6x0d3k8h2m5n7p9q4vc01",
"voucher_ref": "Q7mV2xK9pL4tR8wN3bZ6cH1jYd",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"status": "reserved",
"amount_minor": 2500,
"currency": "USD",
"blockchain_state": "not_created",
"mint_address": null,
"reserved_at": "2026-11-06T09:30:00Z",
"redeemed_at": null,
"voided_at": null,
"object": "voucher",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}Settlements
Settlements are your monthly payouts: month-end close (Japan time), paid at the end of the following month in USDC on Polygon.
List settlements (newest first)
GET/v1/settlements
Required scope: settlements:read
Parameters
-
limitintegerquerymin1max100default25 -
starting_afterstringqueryId of the last object of the current page; returns older objects -
ending_beforestringqueryId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectquerycreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringqueryone ofdraft, confirmed, paid
Returns
Returns a list of Settlement objects.
- 200 OK
- 422 Error — Error
curl "https://www.raz-pay.com/api/v1/settlements?limit=3" \
-H "Authorization: Bearer rz_live_…"{
"object": "list",
"data": [
{
"id": "01jc1a3c5e7g9j1k3m5n7pst01",
"period": "2026-10",
"status": "confirmed",
"currency": "USD",
"item_count": 100,
"gross_minor": 250000,
"fee_minor": 125,
"adjustment_minor": 0,
"carried_minor": 0,
"net_minor": 2375,
"pay_date": "2026-12-31",
"payout_asset": "USDC",
"payout_network": "polygon",
"usdc_amount": "237.231039",
"usdc_rate": null,
"rate_source": null,
"payout_address": null,
"txid": null,
"paid_at": null,
"object": "settlement",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}
],
"has_more": false,
"url": "/v1/settlements"
}Events
The same events that are sent to your webhook endpoints, kept so that you can reconcile deliveries you missed.
Retrieve an event
GET/v1/events/{id}
Required scope: events:read
Parameters
-
idstringpathrequiredpattern^evt_[0-9a-z]{26}$
Returns
Returns the Event object.
- 200 OK
- 404 Error — Error
curl https://www.raz-pay.com/api/v1/events/evt_01jbz6x0d5q7s9v1x3z5b7d9f1 \
-H "Authorization: Bearer rz_live_…"{
"id": "evt_01jbz6x0d5q7s9v1x3z5b7d9f1",
"type": "payment.succeeded",
"occurred_at": "2026-11-06T09:31:12.345Z",
"environment": "test",
"resource_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"resource_version": 1,
"data": {
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "psp_success",
"amount_minor": 2500,
"currency": "USD",
"fee_minor": 125,
"net_minor": 2375,
"item_name": "Premium plan (1 month)",
"quantity": 1,
"payment_link_id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"invoice_id": null,
"created_at": "2026-11-06T09:30:00Z",
"succeeded_at": "2026-11-06T09:31:12Z",
"object": "payment",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
},
"object": "event",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}List events
GET/v1/events
The same events as the webhooks (also recorded when you have no webhook endpoint), newest first. Use it to reconcile webhooks you could not receive. Test pings are not included.
Required scope: events:read
Parameters
-
limitintegerquerymin1max100default10 -
starting_afterstringquerypattern^evt_[0-9a-z]{26}$ -
ending_beforestringquerypattern^evt_[0-9a-z]{26}$ -
createdobjectquerycreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
typestringqueryExact type, or a prefix ending with .* (e.g. payment.*) -
resource_idstringquery
Returns
Returns a list of Event objects.
- 200 OK
- 422 Error — Error
curl "https://www.raz-pay.com/api/v1/events?limit=3&type=payment.*" \
-H "Authorization: Bearer rz_live_…"{
"object": "list",
"data": [
{
"id": "evt_01jbz6x0d5q7s9v1x3z5b7d9f1",
"type": "payment.succeeded",
"occurred_at": "2026-11-06T09:31:12.345Z",
"environment": "test",
"resource_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"resource_version": 1,
"data": {
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "psp_success",
"amount_minor": 2500,
"currency": "USD",
"fee_minor": 125,
"net_minor": 2375,
"item_name": "Premium plan (1 month)",
"quantity": 1,
"payment_link_id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"invoice_id": null,
"created_at": "2026-11-06T09:30:00Z",
"succeeded_at": "2026-11-06T09:31:12Z",
"object": "payment",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
},
"object": "event",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}
],
"has_more": false,
"url": "/v1/events"
}Objects
Checkout Session
-
idstring -
objectstringalways"checkout_session" -
urlstring (uri) | nullRazPay hosted payment page. null when the session is no longer open -
statusstringone ofopen, complete, expired -
payment_statusstringone ofunpaid, paid -
payment_idstring | nullThe successful payment -
namestring -
descriptionstring | null -
product_idstring | null -
quantityinteger -
amount_minorintegerTotal (unit price × quantity) -
currencystring -
display_currencystring -
client_reference_idstring | null -
metadataMetadataUp to 20 pairs. Keys: 1-40 characters [A-Za-z0-9_.-]. Values: strings up to 500 characters (numbers are converted to strings; null or empty removes the key). Returned as an object ({} when empty)max pairs20keys^[A-Za-z0-9_.\-]{1,40}$ -
success_urlstring | nullAs sent (with the {CHECKOUT_SESSION_ID} placeholder) -
cancel_urlstring | null -
customer_prefilledbooleanCustomer details were sent (they are never returned) -
lock_emailboolean -
localestring | nullone ofja, en, null -
auto_eligible_hoursinteger -
expires_atstring (date-time) -
completed_atstring (date-time) | null -
expired_atstring (date-time) | null -
created_atstring (date-time) -
livemodeboolean
{
"id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"object": "checkout_session",
"url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"status": "open",
"payment_status": "unpaid",
"payment_id": null,
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"product_id": null,
"quantity": 1,
"amount_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"success_url": "https://shop.example.com/thanks?session={CHECKOUT_SESSION_ID}",
"cancel_url": "https://shop.example.com/cart",
"customer_prefilled": false,
"lock_email": false,
"locale": "en",
"auto_eligible_hours": 0,
"expires_at": "2026-11-07T09:30:00Z",
"completed_at": null,
"expired_at": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}Payment
-
idstring -
order_idstring -
statusstringone ofcreated, payment_pending, psp_processing, psp_success, failed, cancelled -
amount_minorinteger -
currencystring -
fee_minorinteger -
net_minorinteger -
item_namestring -
quantityinteger -
payment_link_idstring | null -
invoice_idstring | null -
created_atstring (date-time) -
succeeded_atstring (date-time) | null -
objectstringalways"payment" -
livemodeboolean -
checkout_session_idstring | nullCheckout Session the payment was made from -
client_reference_idstring | nullCopied from the Checkout Session or Payment Link -
metadataMetadataUp to 20 pairs. Keys: 1-40 characters [A-Za-z0-9_.-]. Values: strings up to 500 characters (numbers are converted to strings; null or empty removes the key). Returned as an object ({} when empty)max pairs20keys^[A-Za-z0-9_.\-]{1,40}$
{
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "psp_success",
"amount_minor": 2500,
"currency": "USD",
"fee_minor": 125,
"net_minor": 2375,
"item_name": "Premium plan (1 month)",
"quantity": 1,
"payment_link_id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"invoice_id": null,
"created_at": "2026-11-06T09:30:00Z",
"succeeded_at": "2026-11-06T09:31:12Z",
"object": "payment",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
}Transaction
-
idstring -
payment_idstring -
order_idstring -
statusstringpending_sale / fulfillment = payment completed, not yet eligible for settlement (before / after delivery); awaiting_settlement = eligible, included in the next month-end settlement; settled = settlement confirmedone ofpending_sale, fulfillment, awaiting_settlement, settled, cancelled, refunded, on_hold -
settlement_statusstringone ofnot_eligible, awaiting_settlement, settlement_confirmed, excluded -
sale_statusstringone ofpending_sale, fulfillment, actual_sale, cancelled -
holdstring | nullone ofcancel_requested, dispute, manual_review, null -
refund_statusstring | nullone ofrequested, refunded, rejected, null -
amount_minorinteger -
fee_minorinteger -
net_minorinteger -
currencystring -
pending_atstring (date-time) -
auto_eligible_atstring (date-time) | nullBecomes eligible for settlement at this time unless on hold -
fulfilled_atstring (date-time) | null -
actual_sale_atstring (date-time) | null -
cancelled_atstring (date-time) | null -
settlement_idstring | null -
voucher_idstring | null -
versioninteger -
objectstringalways"transaction" -
created_atstring (date-time) -
livemodeboolean -
checkout_session_idstring | null -
client_reference_idstring | null -
metadataMetadataUp to 20 pairs. Keys: 1-40 characters [A-Za-z0-9_.-]. Values: strings up to 500 characters (numbers are converted to strings; null or empty removes the key). Returned as an object ({} when empty)max pairs20keys^[A-Za-z0-9_.\-]{1,40}$
{
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "pending_sale",
"settlement_status": "not_eligible",
"sale_status": "pending_sale",
"hold": null,
"refund_status": null,
"amount_minor": 2500,
"fee_minor": 125,
"net_minor": 2375,
"currency": "USD",
"pending_at": "2026-11-06T09:31:12Z",
"auto_eligible_at": "2026-11-06T09:31:12Z",
"fulfilled_at": null,
"actual_sale_at": null,
"cancelled_at": null,
"settlement_id": null,
"voucher_id": "01jbz6x0d3k8h2m5n7p9q4vc01",
"version": 2,
"object": "transaction",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
}Refund
-
objectstringalways"refund" -
idstring -
payment_idstring -
typestringone ofdirect -
statusstringone ofrequested, refunded, completed, cancelled -
amount_minorinteger -
currencystring -
reasonstring | null -
due_onstring (date) | null -
refunded_onstring (date) | null -
methodstring | nullone ofbank_transfer, crypto_wallet, cash, other, null -
created_atstring (date-time) -
livemodeboolean -
checkout_session_idstring | null -
client_reference_idstring | null -
metadataMetadataUp to 20 pairs. Keys: 1-40 characters [A-Za-z0-9_.-]. Values: strings up to 500 characters (numbers are converted to strings; null or empty removes the key). Returned as an object ({} when empty)max pairs20keys^[A-Za-z0-9_.\-]{1,40}$
{
"object": "refund",
"id": "01jbz7a2c4e6g8j0k2m4n6rf01",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"type": "direct",
"status": "requested",
"amount_minor": 2500,
"currency": "USD",
"reason": "Customer request",
"due_on": null,
"refunded_on": null,
"method": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
}Payment Link
-
idstring -
objectstringalways"payment_link" -
urlstring (uri) -
namestring -
descriptionstring | null -
amount_minorinteger -
currencystring -
display_currencystring -
quantityinteger -
product_idstring | null -
statusstringone ofactive, disabled -
usableboolean -
statestringone ofok, disabled, expired, used, unavailable -
max_usesinteger | null -
uses_countinteger -
auto_eligible_hoursinteger -
expires_atstring (date-time) | null -
created_atstring (date-time) -
purposestringlink = created by the API, email = email payment link, product = product page, invoice = invoiceone oflink, email, product, invoice -
client_reference_idstring | null -
metadataMetadataUp to 20 pairs. Keys: 1-40 characters [A-Za-z0-9_.-]. Values: strings up to 500 characters (numbers are converted to strings; null or empty removes the key). Returned as an object ({} when empty)max pairs20keys^[A-Za-z0-9_.\-]{1,40}$ -
livemodeboolean
{
"id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"object": "payment_link",
"url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"amount_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"quantity": 1,
"product_id": null,
"status": "active",
"usable": true,
"state": "ok",
"max_uses": 1,
"uses_count": 0,
"auto_eligible_hours": 0,
"expires_at": null,
"created_at": "2026-11-06T09:30:00Z",
"purpose": "link",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"livemode": false
}Product
-
idstring -
objectstringalways"product" -
namestring -
descriptionstring | null -
kindstring -
price_minorinteger -
currencystring -
display_currencystring -
activeboolean -
created_atstring (date-time) -
livemodeboolean
{
"id": "01jbz4v6x8z0b2d4f6h8j0pr01",
"object": "product",
"name": "Premium plan (1 month)",
"description": "Monthly subscription",
"kind": "service",
"price_minor": 2500,
"currency": "USD",
"display_currency": "USD",
"active": true,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}Invoice
-
idstring -
objectstringalways"invoice" -
invoice_numberstring -
statusstringone ofdraft, issued, paid, void, refunded -
bill_tostring -
descriptionstring | null -
itemsarray of object -
items[].descriptionstring -
items[].quantityinteger -
items[].unit_price_minorinteger -
items[].amount_minorinteger -
subtotal_minorinteger -
tax_rate_bpinteger -
tax_minorinteger -
amount_minorintegerTotal (tax included) -
currencystring -
localestringone ofen, ja -
issue_datestring (date) | null -
due_datestring (date) -
auto_eligible_hoursinteger -
pay_urlstring (uri) | null -
payment_link_idstring | null -
issued_atstring (date-time) | null -
paid_atstring (date-time) | null -
created_atstring (date-time) -
livemodeboolean
{
"id": "01jbz3t5v7x9z1b3d5f7h9in01",
"object": "invoice",
"invoice_number": "INV-202611-00001",
"status": "issued",
"bill_to": "Sample Trading Ltd.",
"description": "Monthly subscription",
"items": [
{
"description": "Monthly subscription",
"quantity": 1,
"unit_price_minor": 2500,
"amount_minor": 2500
}
],
"subtotal_minor": 2500,
"tax_rate_bp": 0,
"tax_minor": 0,
"amount_minor": 2500,
"currency": "USD",
"locale": "en",
"issue_date": "2026-11-06",
"due_date": "2026-11-30",
"auto_eligible_hours": 0,
"pay_url": "https://www.raz-pay.com/app/pay/3fK9xQ2mWv7LbN8pR4tY6hZ1",
"payment_link_id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"issued_at": "2026-11-06T09:30:00Z",
"paid_at": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}Settlement
-
idstring -
periodstring -
statusstringone ofdraft, confirmed, paid -
currencystring -
item_countinteger -
gross_minorinteger -
fee_minorinteger -
adjustment_minorintegerOffsets deducted from this settlement (negative), e.g. transactions cancelled after an earlier settlement -
carried_minorintegerAmount that could not be offset and is carried to a later settlement (negative) -
net_minorinteger -
pay_datestring (date) -
payout_assetstringAsset the settlement is paid in (always USDC)one ofUSDC -
payout_networkstringNetwork the payout is sent on (always polygon)one ofpolygon -
usdc_amountstring | nullUSDC amount sent, as a decimal string with 6 decimals (truncated); null until the settlement is confirmed -
usdc_ratestring | nullRate fixed when RazPay confirms the settlement: 1 USDC in the settlement currency, as a decimal string with 6 decimals; null until confirmed -
rate_sourcestring | nullWhere the rate came from: the public rate source for automatic rates, or manual for a rate entered by RazPay; null until confirmed -
payout_addressstring | nullPolygon address (0x + 40 hex characters); null until the settlement is confirmed -
txidstring | nullPolygon transaction hash (0x + 64 hex characters), viewable on PolygonScan -
paid_atstring (date-time) | null -
objectstringalways"settlement" -
created_atstring (date-time) -
livemodeboolean
{
"id": "01jc1a3c5e7g9j1k3m5n7pst01",
"period": "2026-10",
"status": "confirmed",
"currency": "USD",
"item_count": 100,
"gross_minor": 250000,
"fee_minor": 125,
"adjustment_minor": 0,
"carried_minor": 0,
"net_minor": 2375,
"pay_date": "2026-12-31",
"payout_asset": "USDC",
"payout_network": "polygon",
"usdc_amount": "237.231039",
"usdc_rate": null,
"rate_source": null,
"payout_address": null,
"txid": null,
"paid_at": null,
"object": "settlement",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}Voucher
-
idstring -
voucher_refstring -
payment_idstring -
statusstringone ofreserved, redeemed, void -
amount_minorinteger -
currencystring -
blockchain_statestringnot_created until NFT issuance is enabled -
mint_addressstring | null -
reserved_atstring (date-time) -
redeemed_atstring (date-time) | null -
voided_atstring (date-time) | null -
objectstringalways"voucher" -
created_atstring (date-time) -
livemodeboolean
{
"id": "01jbz6x0d3k8h2m5n7p9q4vc01",
"voucher_ref": "Q7mV2xK9pL4tR8wN3bZ6cH1jYd",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"status": "reserved",
"amount_minor": 2500,
"currency": "USD",
"blockchain_state": "not_created",
"mint_address": null,
"reserved_at": "2026-11-06T09:30:00Z",
"redeemed_at": null,
"voided_at": null,
"object": "voucher",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}Event
Returned by the Events API. The webhook body is the same without object, created_at and livemode.
-
idstringevt_… (same on retries) -
typestringtransaction.pending_sale = payment completed (not yet eligible for settlement); transaction.actual_sale = eligible for settlement (awaiting settlement). Refund events have two data shapes. Cancellation (processor that can cancel): refund.requested, refund.completed, refund.rejected (the cancellation request was declined); resource_id = payment ID, resource_version = transaction version, data = Transaction. Direct refund (processor that cannot cancel): refund.requested, refund.recorded (the merchant recorded the refund to the customer), refund.completed, refund.withdrawn (the refund request was withdrawn); resource_id = refund ID, resource_version = refund version (increases on every state change), data = RefundEventData. checkout_session.completed (the payment of a Checkout Session succeeded) and checkout_session.expired (expired by time or by the API): resource_id = session ID, data = CheckoutSession. payment.*, transaction.* and refund.* data include checkout_session_id, client_reference_id and metadata.one ofping, payment.succeeded, payment.failed, transaction.pending_sale, transaction.fulfillment, transaction.actual_sale, transaction.on_hold, transaction.hold_released, refund.requested, refund.recorded, refund.rejected, refund.completed, refund.withdrawn, dispute.opened, dispute.resolved, settlement.created, settlement.confirmed, settlement.reverted, settlement.paid, checkout_session.completed, checkout_session.expired -
occurred_atstring (date-time) -
environmentstringone oftest, live -
resource_idstring -
resource_versionintegerIncreases with each change of the resource. Ignore an event whose resource_version is lower than one you already processed for the same resource_id -
dataobjectTransaction, Settlement, etc. depending on type; RefundEventData for direct-refund events -
objectstringalways"event" -
created_atstring (date-time) -
livemodeboolean
{
"id": "evt_01jbz6x0d5q7s9v1x3z5b7d9f1",
"type": "payment.succeeded",
"occurred_at": "2026-11-06T09:31:12.345Z",
"environment": "test",
"resource_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"resource_version": 1,
"data": {
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "psp_success",
"amount_minor": 2500,
"currency": "USD",
"fee_minor": 125,
"net_minor": 2375,
"item_name": "Premium plan (1 month)",
"quantity": 1,
"payment_link_id": "01jbz5w8y0a2c4e6g8j0k2pl01",
"invoice_id": null,
"created_at": "2026-11-06T09:30:00Z",
"succeeded_at": "2026-11-06T09:31:12Z",
"object": "payment",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
},
"object": "event",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
}Refund event data
The data of refund.* events for a direct refund.
-
payment_idstring -
checkout_session_idstring | null -
client_reference_idstring | null -
metadataMetadataUp to 20 pairs. Keys: 1-40 characters [A-Za-z0-9_.-]. Values: strings up to 500 characters (numbers are converted to strings; null or empty removes the key). Returned as an object ({} when empty)max pairs20keys^[A-Za-z0-9_.\-]{1,40}$ -
refundobject -
refund.objectstringalways"refund" -
refund.idstring -
refund.payment_idstring -
refund.typestringone ofdirect -
refund.statusstringone ofrequested, refunded, completed, cancelled -
refund.amount_minorinteger -
refund.currencystring -
refund.reasonstring | null -
refund.due_onstring (date) | null -
refund.refunded_onstring (date) | null -
refund.methodstring | nullone ofbank_transfer, crypto_wallet, cash, other, null -
refund.created_atstring (date-time) -
refund.livemodeboolean -
transactionTransaction
{
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
},
"refund": {
"object": "refund",
"id": "01jbz7a2c4e6g8j0k2m4n6rf01",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"type": "direct",
"status": "requested",
"amount_minor": 2500,
"currency": "USD",
"reason": "Customer request",
"due_on": null,
"refunded_on": null,
"method": null,
"created_at": "2026-11-06T09:30:00Z",
"livemode": false
},
"transaction": {
"id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"payment_id": "01jbz6x0d3k8h2m5n7p9q4r6s8",
"order_id": "RP261106093000ABC123",
"status": "pending_sale",
"settlement_status": "not_eligible",
"sale_status": "pending_sale",
"hold": null,
"refund_status": null,
"amount_minor": 2500,
"fee_minor": 125,
"net_minor": 2375,
"currency": "USD",
"pending_at": "2026-11-06T09:31:12Z",
"auto_eligible_at": "2026-11-06T09:31:12Z",
"fulfilled_at": null,
"actual_sale_at": null,
"cancelled_at": null,
"settlement_id": null,
"voucher_id": "01jbz6x0d3k8h2m5n7p9q4vc01",
"version": 2,
"object": "transaction",
"created_at": "2026-11-06T09:30:00Z",
"livemode": false,
"checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42"
}
}
}List
Every list endpoint returns this object. data holds the objects of the resource, newest first.
-
objectstringalways"list" -
dataarray of any -
has_morebooleantrue if there are more objects in the direction you paginate -
urlstring
{
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/payments"
}Metadata
Your own key-value pairs on Checkout Sessions and Payment Links, copied to their payments.
{
"customer_id": "c_42"
}Error
Every error response has this body. Branch on error.code; error.message is for people.
-
errorobject -
error.codestring -
error.messagestringHuman-readable message. English by default; Japanese when the request sends Accept-Language: ja -
error.fieldsobject -
request_idstring
{
"error": {
"code": "validation_failed",
"message": "Some fields are invalid.",
"fields": {
"amount_minor": [
"The amount minor field must be at least 100."
]
}
},
"request_id": "01JBZ6X0F2H4K6M8P0R2T4W6Y8"
}