Skip to content
RazPay. API Reference

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.

Base URL https://www.raz-pay.com/api/v1

OpenAPI 3.1 (YAML) OpenAPI 3.1 (JSON)

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

  1. Create a Checkout Session on your server (POST /checkout-sessions) with the item, amount, your order number in client_reference_id, and success_url / cancel_url.
  2. Redirect the customer to the session url. The customer enters their details and pays on the payment processor's page.
  3. Receive the payment.succeeded webhook, verify its signature, and fulfil the order. The redirect to success_url is a convenience only.
  4. Track the sale with the Transactions API and your monthly payouts with the Settlements API.
Example request · POST /checkout-sessions
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.

ScopeAllows
payments:readRetrieve and list payments
payment_links:readRetrieve and list Payment Links
payment_links:writeCreate and deactivate Payment Links
products:writeCreate products
invoices:writeCreate and issue invoices
refunds:writeRequest cancellations and direct refunds
transactions:readRetrieve and list transactions
vouchers:readRetrieve vouchers
settlements:readList settlements
checkout_sessions:readRetrieve and list Checkout Sessions
checkout_sessions:writeCreate and expire Checkout Sessions
products:readRetrieve and list products
invoices:readRetrieve and list invoices
refunds:readRetrieve and list direct refunds
events:readRetrieve and list events
Example request
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.

StatusMeaning
200OK
201Created
202Accepted (the request is processed afterwards)
400The request is malformed (e.g. a missing Idempotency-Key, or a body that is not a JSON object)
401No valid API key
403The key lacks a scope, or the account cannot do this now
404The object or endpoint does not exist (or belongs to another merchant)
405The method is not allowed for the endpoint (the `Allow` header lists the allowed methods)
409Conflicts with the current state of the object or with an earlier request
422Some fields are invalid
429Too many requests
500Internal error (retry later)
error.codeMeaning
unauthorizedNo API key, an invalid or revoked key, or a key of the other environment.
insufficient_scopeThe key does not have the scope of the endpoint.
not_foundThe object or endpoint does not exist, or belongs to another merchant.
validation_failedSome fields are invalid. See error.fields.
invalid_jsonThe request body is not valid JSON or not a JSON object.
idempotency_key_requiredA POST without a valid Idempotency-Key header.
idempotency_conflictThe Idempotency-Key was used with a different request body.
request_in_progressA request with the same Idempotency-Key is still being processed.
rate_limitedToo many requests. Wait for Retry-After seconds.
not_refundableThe payment cannot be cancelled or refunded in its current state.
cancellation_period_passedThe payment processor's cancellation period has passed.
partial_refund_not_supportedPartial cancellation is not supported for this payment.
amount_invalidThe refund amount is larger than the remaining refundable amount.
payments_not_enabledThe account cannot accept payments yet.
merchant_suspendedThe account is suspended and cannot accept new payments.
merchant_closedThe account is closed and cannot accept new payments.
merchant_unavailableThe merchant account is not available.
checkout_session_not_openThe Checkout Session is already complete or expired.
checkout_session_in_progressA payment for the Checkout Session is being processed.
payment_link_not_deactivatableLinks of product pages and invoices cannot be deactivated.
method_not_allowedThe HTTP method is not allowed for the endpoint.
internal_errorAn error on RazPay's side. Retry later; contact support with the request_id if it continues.
HTTP 422
{
  "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.

Example request
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.

Example
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: true

Metadata

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.

Example
{
    "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:

HeaderDescription
X-RazPay-Event-IdThe event id (evt_…). The same on every retry of the event.
X-RazPay-TimestampUnix time (seconds) when this delivery attempt was signed.
X-RazPay-Signaturev1= followed by the hex HMAC-SHA256 of the signed payload, computed with your signing secret.
Content-Typeapplication/json
User-AgentRazPay-Webhooks/1.0

Verify the signature

  1. Read the raw request body exactly as received (before any JSON parsing).
  2. Build the signed payload: the value of X-RazPay-Timestamp, a period (.), and the raw body.
  3. 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 with v1=.
  4. Compare it with X-RazPay-Signature using a constant-time comparison. Reject the request if they differ.
  5. Reject the request if the timestamp is more than 5 minutes away from your server time (protection against replays).
  6. 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, 429 or 5xx, 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 whose resource_version is lower than one you have already processed for the same resource_id.
  • The Merchant Console can send a test event with type ping to an endpoint. Every other event is also available from the Events API.
signed_payload
signed_payload = X-RazPay-Timestamp + "." + raw_body
X-RazPay-Signature = "v1=" + hex(HMAC_SHA256(key = whsec_…, signed_payload))
PHP
$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);
Node.js (Express)
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);
});
Event body · payment.succeeded
{
  "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 typedataDescription
payment.succeededPaymentA payment succeeded. Fulfil the order after this event.
payment.failedPaymentA payment failed or was declined.
transaction.pending_saleTransactionA transaction was created for a successful payment (not yet eligible for settlement).
transaction.fulfillmentTransactionThe order was marked as delivered.
transaction.actual_saleTransactionThe transaction became eligible for settlement (receipt confirmed by the customer, automatically after the set time, or by RazPay).
transaction.on_holdTransactionThe transaction was put on hold for review.
transaction.hold_releasedTransactionThe hold was released.
refund.requestedTransaction / Refund event dataA cancellation or a direct refund was requested.
refund.recordedRefund event dataYou recorded the direct refund to the customer.
refund.rejectedTransactionThe cancellation request was declined.
refund.completedTransaction / Refund event dataThe cancellation or the direct refund was completed.
refund.withdrawnRefund event dataThe direct refund request was withdrawn.
dispute.openedTransactionThe customer reported a problem with the order; the transaction is on hold.
dispute.resolvedTransactionThe reported problem was resolved and the hold released.
settlement.createdSettlementA monthly settlement was created (draft).
settlement.confirmedSettlementThe settlement was confirmed, with the USDC amount and rate fixed.
settlement.revertedSettlementThe confirmation was withdrawn before payout and the settlement returned to draft (it will be confirmed again).
settlement.paidSettlementThe payout was sent (USDC on Polygon; txid is set).
checkout_session.completedCheckout SessionThe payment of a Checkout Session succeeded.
checkout_session.expiredCheckout SessionA 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 429
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-Keystringheaderrequired
    pattern ^[A-Za-z0-9_\-:.]{8,100}$

Request body application/json

  • product_idstring
    Product id (26 chars)
  • namestring
    Item name shown on the payment page (required without product_id)
    max length 100
  • descriptionstring
    max length 1000
  • amount_minorinteger
    Unit price in minor units (required without product_id). The total (× quantity) must be within your minimum and maximum per payment
    min 100max 99999999
  • quantityinteger
    min 1max 999default 1
  • currencystring
    Your account currency. Other values are rejected
    one of MYR, USD, AED
  • display_currencystring
    Reference display only
    one of MYR, USD, AED, JPY
  • client_reference_idstring
    Your own reference (e.g. order number). Filter with GET /checkout-sessions?client_reference_id= and GET /payments?client_reference_id=
    max length 200
  • metadataMetadata
    Up 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 pairs 20keys ^[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 page
    max length 2000
  • 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_url
    max length 2000
  • customerobject
    Prefill the payment form. The customer can change name and phone. These values are never returned by the API or webhooks
  • customer.namestring
    max length 100
  • customer.emailstring (email)
    max length 150
  • customer.phonestring
    International format recommended (+819012345678)
  • customer.lock_emailboolean
    true = the email cannot be changed and only this email can pay (requires customer.email)
    default false
  • localestring
    Language of the payment page (default English; the customer can switch)
    one of ja, en
  • expires_atinteger | string (date-time)
    30 minutes to 7 days from now. Default: 24 hours
  • auto_eligible_hoursinteger
    min 0max 168default 0

Returns

Returns the Checkout Session object.

Example request
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"
    }'
Example response · 201
{
  "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

  • idstringpathrequired
    pattern ^[0-9a-z]{26}$

Returns

Returns the Checkout Session object.

  • 200 OK
  • 404 Error — Error
Example request
curl https://www.raz-pay.com/api/v1/checkout-sessions/01jbz6x0d3k8h2m5n7p9q4cs01 \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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

  • limitintegerquery
    min 1max 100default 10
  • starting_afterstringquery
    Id of the last object of the current page; returns older objects
  • ending_beforestringquery
    Id of the first object of the current page; returns newer objects. Not together with starting_after
  • createdobjectquery
    created[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset)
  • statusstringquery
    one of open, complete, expired
  • client_reference_idstringquery
  • payment_idstringquery

Returns

Returns a list of Checkout Session objects.

  • 200 OK
  • 422 Error — Error
Example request
curl "https://www.raz-pay.com/api/v1/checkout-sessions?limit=3" \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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

  • idstringpathrequired
    pattern ^[0-9a-z]{26}$
  • Idempotency-Keystringheaderrequired
    pattern ^[A-Za-z0-9_\-:.]{8,100}$

Returns

Returns the Checkout Session object.

Example request
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"
Example response · 200
{
  "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
}

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-Keystringheaderrequired
    pattern ^[A-Za-z0-9_\-:.]{8,100}$

Request body application/json

  • namestringrequired
    max length 100
  • descriptionstring
    max length 1000
  • kindstring
    one of service, goods, otherdefault service
  • price_minorintegerrequired
    min 100max 99999999
  • currencystring
    Your account currency (set by the payment processor of your account). Other values are rejected
    one of MYR, USD, AED
  • display_currencystring
    one of MYR, USD, AED, JPY

Returns

Returns the Product object.

Example request
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"
    }'
Example response · 201
{
  "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

  • idstringpathrequired
    pattern ^[0-9a-z]{26}$

Returns

Returns the Product object.

  • 200 OK
  • 404 Error — Error
Example request
curl https://www.raz-pay.com/api/v1/products/01jbz4v6x8z0b2d4f6h8j0pr01 \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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

  • limitintegerquery
    min 1max 100default 10
  • starting_afterstringquery
    Id of the last object of the current page; returns older objects
  • ending_beforestringquery
    Id of the first object of the current page; returns newer objects. Not together with starting_after
  • createdobjectquery
    created[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
Example request
curl "https://www.raz-pay.com/api/v1/products?limit=3" \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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-Keystringheaderrequired
    pattern ^[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_tostringrequired
    max length 100
  • bill_to_emailstring (email)
    If set, the invoice is emailed when issued, with the PDF attached and the payment link
  • bill_to_addressstring
    max length 500
  • descriptionstring
    max length 150
  • amount_minorinteger
    Tax included. Required when items is not sent
    min 100max 99999999
  • itemsarray of object
    min items 1max items 20
  • items[].descriptionstringrequired
    max length 191
  • items[].quantityintegerrequired
    min 1max 100000
  • items[].unit_price_minorintegerrequired
    min 0
  • tax_rate_bpinteger
    Tax rate in basis points (600 = 6%). Tax = subtotal × rate, rounded to the nearest minor unit (1/100)
    min 0max 10000default 0
  • currencystring
    Your account currency (set by the payment processor of your account). Other values are rejected
    one of MYR, USD, AED
  • issue_datestring (date)
  • due_datestring (date)required
  • notesstring
    max length 1000
  • auto_eligible_hoursinteger
    Hours 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)
    min 0max 168default 0
  • issueboolean
    default true
  • localestring
    one of en, ja

Returns

Returns the Invoice object.

Example request
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"
    }'
Example response · 201
{
  "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

  • idstringpathrequired
    pattern ^[0-9a-z]{26}$

Returns

Returns the Invoice object.

  • 200 OK
  • 404 Error — Error
Example request
curl https://www.raz-pay.com/api/v1/invoices/01jbz3t5v7x9z1b3d5f7h9in01 \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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

  • limitintegerquery
    min 1max 100default 10
  • starting_afterstringquery
    Id of the last object of the current page; returns older objects
  • ending_beforestringquery
    Id of the first object of the current page; returns newer objects. Not together with starting_after
  • createdobjectquery
    created[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset)
  • statusstringquery
    one of draft, issued, paid, void, refunded

Returns

Returns a list of Invoice objects.

  • 200 OK
  • 422 Error — Error
Example request
curl "https://www.raz-pay.com/api/v1/invoices?limit=3" \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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

  • idstringpathrequired
    pattern ^[0-9a-z]{26}$

Returns

Returns the Payment object.

  • 200 OK
  • 404 Error — Error
Response fields
  • idstring
  • order_idstring
  • statusstring
    one of created, 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
  • objectstring
    always "payment"
  • livemodeboolean
  • checkout_session_idstring | null
    Checkout Session the payment was made from
  • client_reference_idstring | null
    Copied from the Checkout Session or Payment Link
  • metadataMetadata
    Up 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 pairs 20keys ^[A-Za-z0-9_.\-]{1,40}$
  • transactionTransaction | null
Example request
curl https://www.raz-pay.com/api/v1/payments/01jbz6x0d3k8h2m5n7p9q4r6s8 \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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

  • limitintegerquery
    min 1max 100default 10
  • starting_afterstringquery
    Id of the last object of the current page; returns older objects
  • ending_beforestringquery
    Id of the first object of the current page; returns newer objects. Not together with starting_after
  • createdobjectquery
    created[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset)
  • statusstringquery
    one of created, payment_pending, psp_processing, psp_success, failed, cancelled
  • client_reference_idstringquery

Returns

Returns the object described below.

  • 200 OK
  • 422 Error — Error
Response fields
  • objectstring
    always "list"
  • dataarray of Payment
  • data[].idstring
  • data[].order_idstring
  • data[].statusstring
    one of created, 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[].objectstring
    always "payment"
  • data[].livemodeboolean
  • data[].checkout_session_idstring | null
    Checkout Session the payment was made from
  • data[].client_reference_idstring | null
    Copied from the Checkout Session or Payment Link
  • data[].metadataMetadata
    Up 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 pairs 20keys ^[A-Za-z0-9_.\-]{1,40}$
  • data[].transactionTransaction | null
    The transaction of a successful payment (null otherwise), as in GET /payments/{id}
  • has_moreboolean
    true if there are more objects in the direction you paginate
  • urlstring
Example request
curl "https://www.raz-pay.com/api/v1/payments?limit=3" \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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

  • idstringpathrequired
    pattern ^[0-9a-z]{26}$

Returns

Returns the Transaction object.

  • 200 OK
  • 404 Error — Error
Example request
curl https://www.raz-pay.com/api/v1/transactions/01jbz6x0d3k8h2m5n7p9q4r6s8 \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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

  • limitintegerquery
    min 1max 100default 10
  • starting_afterstringquery
    Id of the last object of the current page; returns older objects
  • ending_beforestringquery
    Id of the first object of the current page; returns newer objects. Not together with starting_after
  • createdobjectquery
    created[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset)
  • statusstringquery
    sale_status
    one of pending_sale, fulfillment, actual_sale, cancelled

Returns

Returns a list of Transaction objects.

  • 200 OK
  • 422 Error — Error
Example request
curl "https://www.raz-pay.com/api/v1/transactions?limit=3" \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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-Keystringheaderrequired
    pattern ^[A-Za-z0-9_\-:.]{8,100}$

Request body application/json

  • payment_idstringrequired
  • amount_minorinteger
    Optional. Cancellation: must equal the payment amount. Direct refund: 1 to the remaining refundable amount (default: all)
  • reasonstringrequired
    max length 1000

Returns

Returns the object described below.

Response fields
  • objectstring
    always "refund"
  • idstring
    Direct refund only: the refund ID (resource_id of refund.* webhooks for direct refunds). Absent for a cancellation request
  • typestring
    Direct refund only. Absent for a cancellation request
    one of direct
  • payment_idstring
  • statusstring
    Always requested in this response. Later states of a direct refund (webhook data.refund.status): refunded, completed, cancelled
    one of requested
  • amount_minorinteger
  • currencystring
  • reasonstring | null
    Direct refund only
  • due_onstring (date) | null
    Direct refund only: planned refund date (Japan time), if set
  • refunded_onstring (date) | null
    Direct refund only: date the merchant refunded the customer; null until recorded
  • methodstring | null
    Direct refund only: how the merchant refunded; null until recorded
    one of bank_transfer, crypto_wallet, cash, other, null
  • created_atstring (date-time)
    Direct refund only
  • livemodeboolean
    Direct refund only
  • transactionTransaction
Example request
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"
    }'
Example response · 202
{
  "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

  • idstringpathrequired
    pattern ^[0-9a-z]{26}$

Returns

Returns the Refund object.

  • 200 OK
  • 404 Error — Error
Example request
curl https://www.raz-pay.com/api/v1/refunds/01jbz7a2c4e6g8j0k2m4n6rf01 \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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

  • limitintegerquery
    min 1max 100default 10
  • starting_afterstringquery
    Id of the last object of the current page; returns older objects
  • ending_beforestringquery
    Id of the first object of the current page; returns newer objects. Not together with starting_after
  • createdobjectquery
    created[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset)
  • statusstringquery
    one of requested, refunded, completed, cancelled
  • payment_idstringquery

Returns

Returns a list of Refund objects.

  • 200 OK
  • 422 Error — Error
Example request
curl "https://www.raz-pay.com/api/v1/refunds?limit=3" \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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

  • idstringpathrequired
    pattern ^[0-9a-z]{26}$

Returns

Returns the Voucher object.

  • 200 OK
  • 404 Error — Error
Example request
curl https://www.raz-pay.com/api/v1/vouchers/01jbz6x0d3k8h2m5n7p9q4vc01 \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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

  • limitintegerquery
    min 1max 100default 25
  • starting_afterstringquery
    Id of the last object of the current page; returns older objects
  • ending_beforestringquery
    Id of the first object of the current page; returns newer objects. Not together with starting_after
  • createdobjectquery
    created[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset)
  • statusstringquery
    one of draft, confirmed, paid

Returns

Returns a list of Settlement objects.

  • 200 OK
  • 422 Error — Error
Example request
curl "https://www.raz-pay.com/api/v1/settlements?limit=3" \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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

  • idstringpathrequired
    pattern ^evt_[0-9a-z]{26}$

Returns

Returns the Event object.

  • 200 OK
  • 404 Error — Error
Example request
curl https://www.raz-pay.com/api/v1/events/evt_01jbz6x0d5q7s9v1x3z5b7d9f1 \
  -H "Authorization: Bearer rz_live_…"
Example response · 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"
    }
  },
  "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

  • limitintegerquery
    min 1max 100default 10
  • starting_afterstringquery
    pattern ^evt_[0-9a-z]{26}$
  • ending_beforestringquery
    pattern ^evt_[0-9a-z]{26}$
  • createdobjectquery
    created[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset)
  • typestringquery
    Exact type, or a prefix ending with .* (e.g. payment.*)
  • resource_idstringquery

Returns

Returns a list of Event objects.

  • 200 OK
  • 422 Error — Error
Example request
curl "https://www.raz-pay.com/api/v1/events?limit=3&type=payment.*" \
  -H "Authorization: Bearer rz_live_…"
Example response · 200
{
  "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
  • objectstring
    always "checkout_session"
  • urlstring (uri) | null
    RazPay hosted payment page. null when the session is no longer open
  • statusstring
    one of open, complete, expired
  • payment_statusstring
    one of unpaid, paid
  • payment_idstring | null
    The successful payment
  • namestring
  • descriptionstring | null
  • product_idstring | null
  • quantityinteger
  • amount_minorinteger
    Total (unit price × quantity)
  • currencystring
  • display_currencystring
  • client_reference_idstring | null
  • metadataMetadata
    Up 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 pairs 20keys ^[A-Za-z0-9_.\-]{1,40}$
  • success_urlstring | null
    As sent (with the {CHECKOUT_SESSION_ID} placeholder)
  • cancel_urlstring | null
  • customer_prefilledboolean
    Customer details were sent (they are never returned)
  • lock_emailboolean
  • localestring | null
    one of ja, en, null
  • auto_eligible_hoursinteger
  • expires_atstring (date-time)
  • completed_atstring (date-time) | null
  • expired_atstring (date-time) | null
  • created_atstring (date-time)
  • livemodeboolean
Example · CheckoutSession
{
  "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
  • statusstring
    one of created, 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
  • objectstring
    always "payment"
  • livemodeboolean
  • checkout_session_idstring | null
    Checkout Session the payment was made from
  • client_reference_idstring | null
    Copied from the Checkout Session or Payment Link
  • metadataMetadata
    Up 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 pairs 20keys ^[A-Za-z0-9_.\-]{1,40}$
Example · Payment
{
  "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
  • statusstring
    pending_sale / fulfillment = payment completed, not yet eligible for settlement (before / after delivery); awaiting_settlement = eligible, included in the next month-end settlement; settled = settlement confirmed
    one of pending_sale, fulfillment, awaiting_settlement, settled, cancelled, refunded, on_hold
  • settlement_statusstring
    one of not_eligible, awaiting_settlement, settlement_confirmed, excluded
  • sale_statusstring
    one of pending_sale, fulfillment, actual_sale, cancelled
  • holdstring | null
    one of cancel_requested, dispute, manual_review, null
  • refund_statusstring | null
    one of requested, refunded, rejected, null
  • amount_minorinteger
  • fee_minorinteger
  • net_minorinteger
  • currencystring
  • pending_atstring (date-time)
  • auto_eligible_atstring (date-time) | null
    Becomes 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
  • objectstring
    always "transaction"
  • created_atstring (date-time)
  • livemodeboolean
  • checkout_session_idstring | null
  • client_reference_idstring | null
  • metadataMetadata
    Up 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 pairs 20keys ^[A-Za-z0-9_.\-]{1,40}$
Example · 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"
  }
}

Refund

  • objectstring
    always "refund"
  • idstring
  • payment_idstring
  • typestring
    one of direct
  • statusstring
    one of requested, refunded, completed, cancelled
  • amount_minorinteger
  • currencystring
  • reasonstring | null
  • due_onstring (date) | null
  • refunded_onstring (date) | null
  • methodstring | null
    one of bank_transfer, crypto_wallet, cash, other, null
  • created_atstring (date-time)
  • livemodeboolean
  • checkout_session_idstring | null
  • client_reference_idstring | null
  • metadataMetadata
    Up 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 pairs 20keys ^[A-Za-z0-9_.\-]{1,40}$
Example · 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,
  "checkout_session_id": "01jbz6x0d3k8h2m5n7p9q4cs01",
  "client_reference_id": "order-1001",
  "metadata": {
    "customer_id": "c_42"
  }
}

Product

  • idstring
  • objectstring
    always "product"
  • namestring
  • descriptionstring | null
  • kindstring
  • price_minorinteger
  • currencystring
  • display_currencystring
  • activeboolean
  • created_atstring (date-time)
  • livemodeboolean
Example · Product
{
  "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
  • objectstring
    always "invoice"
  • invoice_numberstring
  • statusstring
    one of draft, 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_minorinteger
    Total (tax included)
  • currencystring
  • localestring
    one of en, 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
Example · Invoice
{
  "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
  • statusstring
    one of draft, confirmed, paid
  • currencystring
  • item_countinteger
  • gross_minorinteger
  • fee_minorinteger
  • adjustment_minorinteger
    Offsets deducted from this settlement (negative), e.g. transactions cancelled after an earlier settlement
  • carried_minorinteger
    Amount that could not be offset and is carried to a later settlement (negative)
  • net_minorinteger
  • pay_datestring (date)
  • payout_assetstring
    Asset the settlement is paid in (always USDC)
    one of USDC
  • payout_networkstring
    Network the payout is sent on (always polygon)
    one of polygon
  • usdc_amountstring | null
    USDC amount sent, as a decimal string with 6 decimals (truncated); null until the settlement is confirmed
  • usdc_ratestring | null
    Rate fixed when RazPay confirms the settlement: 1 USDC in the settlement currency, as a decimal string with 6 decimals; null until confirmed
  • rate_sourcestring | null
    Where the rate came from: the public rate source for automatic rates, or manual for a rate entered by RazPay; null until confirmed
  • payout_addressstring | null
    Polygon address (0x + 40 hex characters); null until the settlement is confirmed
  • txidstring | null
    Polygon transaction hash (0x + 64 hex characters), viewable on PolygonScan
  • paid_atstring (date-time) | null
  • objectstring
    always "settlement"
  • created_atstring (date-time)
  • livemodeboolean
Example · Settlement
{
  "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
  • statusstring
    one of reserved, redeemed, void
  • amount_minorinteger
  • currencystring
  • blockchain_statestring
    not_created until NFT issuance is enabled
  • mint_addressstring | null
  • reserved_atstring (date-time)
  • redeemed_atstring (date-time) | null
  • voided_atstring (date-time) | null
  • objectstring
    always "voucher"
  • created_atstring (date-time)
  • livemodeboolean
Example · Voucher
{
  "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.

  • idstring
    evt_… (same on retries)
  • typestring
    transaction.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 of ping, 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)
  • environmentstring
    one of test, live
  • resource_idstring
  • resource_versioninteger
    Increases with each change of the resource. Ignore an event whose resource_version is lower than one you already processed for the same resource_id
  • dataobject
    Transaction, Settlement, etc. depending on type; RefundEventData for direct-refund events
  • objectstring
    always "event"
  • created_atstring (date-time)
  • livemodeboolean
Example · Event
{
  "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
  • metadataMetadata
    Up 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 pairs 20keys ^[A-Za-z0-9_.\-]{1,40}$
  • refundobject
  • refund.objectstring
    always "refund"
  • refund.idstring
  • refund.payment_idstring
  • refund.typestring
    one of direct
  • refund.statusstring
    one of requested, refunded, completed, cancelled
  • refund.amount_minorinteger
  • refund.currencystring
  • refund.reasonstring | null
  • refund.due_onstring (date) | null
  • refund.refunded_onstring (date) | null
  • refund.methodstring | null
    one of bank_transfer, crypto_wallet, cash, other, null
  • refund.created_atstring (date-time)
  • refund.livemodeboolean
  • transactionTransaction
Example · RefundEventData
{
  "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.

  • objectstring
    always "list"
  • dataarray of any
  • has_moreboolean
    true if there are more objects in the direction you paginate
  • urlstring
Example · List
{
  "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.

Example · Metadata
{
  "customer_id": "c_42"
}

Error

Every error response has this body. Branch on error.code; error.message is for people.

  • errorobject
  • error.codestring
  • error.messagestring
    Human-readable message. English by default; Japanese when the request sends Accept-Language: ja
  • error.fieldsobject
  • request_idstring
Example · Error
{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": {
      "amount_minor": [
        "The amount minor field must be at least 100."
      ]
    }
  },
  "request_id": "01JBZ6X0F2H4K6M8P0R2T4W6Y8"
}