RazPay API v1.0
API リファレンス
RazPay API は HTTPS の REST API です。リクエストとレスポンスは JSON(UTF-8)で、すべてのリクエストを加盟店アカウントの API キーで認証します。日時は UTC の ISO 8601 です。
https://www.raz-pay.com/api/v1
はじめに
お支払いは必ず RazPay のお支払い画面(ホスト型の決済ページ)で行います。API で Checkout Session・Payment Link・請求書を作成し、お客様をその URL へ案内してください。カード情報は決済代行会社の画面で入力され、加盟店のサーバーにも RazPay にも届きません。カード番号を直接受け取る API はありません。
金額は、アカウントの通貨の最小単位(1/100)の整数で書きます。250.00 は 25000 です。1 回の決済の最低金額は 1.00、1 回の決済の最高金額は 100,000.00 です(アカウントの通貨)。どちらも RazPay が設定し、最高金額は契約によりアカウントごとに異なることがあります。範囲外の金額は 422 validation_failed になります。
テスト用のキーはテスト環境(https://www.raz-pay.com/staging/api/v1)だけ、本番用のキーは本番(https://www.raz-pay.com/api/v1)だけで使えます。テスト環境は同じ API なので、本番の前に連携を作って確かめられます。
本文は JSON のオブジェクト(Content-Type: application/json)で送ります。読めない本文は 400 invalid_json です。文字の項目に制御文字は使えません(説明・メモ・理由・metadata の値は改行とタブだけ使えます)。前後の空白は取り除きます。
基本の流れ
- 加盟店のサーバーで Checkout Session を作成します(
POST /checkout-sessions)。品目・金額・注文番号(client_reference_id)・success_url・cancel_urlを指定します。 - お客様をセッションの
urlへ移します。お客様は情報を入力し、決済代行会社の画面で支払います。 - Webhook の
payment.succeededを受け取り、署名を確かめてから商品を提供します。success_urlへの移動は補助です(それだけを頼りにしないでください)。 - 売上は取引(Transactions)API、月ごとの支払いは精算(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"
}'認証
API キーを Authorization ヘッダーの Bearer トークンとして送ります。キーの接頭辞は、本番が rz_live_、テスト環境が rz_test_ です。もう一方の環境のキーは 401 unauthorized になります。
キーは加盟店アカウントのオーナーが Merchant Console(APIキー)で作成します。キーは作成したときに一度だけ表示し、RazPay はハッシュだけを保存します。有効なキーは 10 個まで持て、いつでも失効できます。
キーごとにスコープ(権限)があります。キーに無いスコープの操作は 403 insufficient_scope です。システムごとに必要なスコープだけを付けてください。
キーは加盟店のサーバーに置き、Web ページ・スマホアプリ・公開のリポジトリには入れないでください。
| スコープ | できること |
|---|---|
payments:read | 決済の照会・一覧 |
payment_links:read | Payment Link の照会・一覧 |
payment_links:write | Payment Link の作成・停止 |
products:write | 商品の作成 |
invoices:write | 請求書の作成・発行 |
refunds:write | 取消・直接の返金の申請 |
transactions:read | 取引の照会・一覧 |
vouchers:read | Voucher の照会 |
settlements:read | 精算の一覧 |
checkout_sessions:read | Checkout Session の照会・一覧 |
checkout_sessions:write | Checkout Session の作成・終了 |
products:read | 商品の照会・一覧 |
invoices:read | 請求書の照会・一覧 |
refunds:read | 直接の返金の照会・一覧 |
events:read | イベントの照会・一覧 |
curl https://www.raz-pay.com/api/v1/payments?limit=3 \
-H "Authorization: Bearer rz_live_…"エラー
HTTP のステータスコードを使います。2xx は成功、4xx はリクエストの問題、5xx は RazPay 側の問題です(時間をおいて再送してください)。エラーの本文には error.code・error.message・error.fields(validation_failed のとき、項目名 → メッセージ)・request_id があります。
メッセージは既定で英語です。Accept-Language: ja を送ると message と fields が日本語になります。code は言語に関係なく同じなので、処理の分岐は message ではなく code で行ってください。お問い合わせの際は request_id をお知らせください。
| ステータス | 意味 |
|---|---|
200 | 成功 |
201 | 作成しました |
202 | 受け付けました(処理はこの後に行います) |
400 | リクエストの形式の誤り(Idempotency-Key が無い、本文が JSON のオブジェクトでないなど) |
401 | 有効な API キーがありません |
403 | キーにスコープが無い、またはアカウントが今この操作をできません |
404 | オブジェクトまたはエンドポイントがありません(他の加盟店のものを含む) |
405 | このエンドポイントでは使えないメソッドです(使えるメソッドは `Allow` ヘッダー) |
409 | オブジェクトの今の状態、または前のリクエストと矛盾します |
422 | 入力に誤りがあります |
429 | リクエストが多すぎます |
500 | 内部のエラー(時間をおいて再送してください) |
| error.code | 意味 |
|---|---|
unauthorized | API キーが無い、正しくない・失効した、またはもう一方の環境のキーです。 |
insufficient_scope | キーにエンドポイントのスコープがありません。 |
not_found | オブジェクトまたはエンドポイントがありません(他の加盟店のものを含む)。 |
validation_failed | 入力に誤りがあります。error.fields を確認してください。 |
invalid_json | リクエストの本文が正しい JSON のオブジェクトではありません。 |
idempotency_key_required | POST に正しい Idempotency-Key ヘッダーがありません。 |
idempotency_conflict | その Idempotency-Key は別の本文で使われています。 |
request_in_progress | 同じ Idempotency-Key のリクエストを処理中です。 |
rate_limited | リクエストが多すぎます。Retry-After の秒数を待ってください。 |
not_refundable | 今の状態の決済は取消・返金できません。 |
cancellation_period_passed | 決済代行会社の取消可能期間を過ぎています。 |
partial_refund_not_supported | この決済は一部の取消ができません。 |
amount_invalid | 返金額が返金できる残りの額より大きいです。 |
payments_not_enabled | アカウントはまだ決済を受け付けられません。 |
merchant_suspended | アカウントは一時停止中で、新しい決済を受け付けられません。 |
merchant_closed | アカウントは利用を終了しており、新しい決済を受け付けられません。 |
merchant_unavailable | 加盟店アカウントを利用できません。 |
checkout_session_not_open | Checkout Session はすでに完了または期限切れです。 |
checkout_session_in_progress | Checkout Session の支払いを処理中です。 |
payment_link_not_deactivatable | 商品ページ・請求書のリンクは停止できません。 |
method_not_allowed | このエンドポイントでは使えない HTTP メソッドです。 |
internal_error | RazPay 側のエラーです。時間をおいて再送し、続く場合は request_id を添えてお問い合わせください。 |
{
"error": {
"code": "validation_failed",
"message": "Some fields are invalid.",
"fields": {
"amount_minor": [
"The amount minor field must be at least 100."
]
}
},
"request_id": "01JBZ6X0F2H4K6M8P0R2T4W6Y8"
}一覧とページ送り
一覧は {"object": "list", "data": [...], "has_more": true, "url": "/v1/payments"} の形で、新しい順です。limit は 1〜100(既定 10、精算は 25)。
次の(古い)ページは starting_after に今のページの最後のオブジェクトの ID を、前の(新しい)ページは ending_before に最初のオブジェクトの ID を指定します。両方は同時に指定できません。has_more は、その方向にまだオブジェクトがあるかを表します。
作成日時で絞り込むときは created[gte]・created[gt]・created[lte]・created[lt](UNIX 秒、または ISO 8601。時差が無ければ UTC)を使います。そのほか、エンドポイントごとの絞り込みがあります。query の値は 1 つだけです(status[]=open のような配列は 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(重複の防止)
すべての POST に Idempotency-Key ヘッダーが必要です。8〜100 文字の英数字と - _ : . です。無いと 400 idempotency_key_required です。
操作ごとに 1 つのキー(注文番号など)を使ってください。タイムアウトしたら、同じキー・同じ本文で再送します。最初の応答(ヘッダー Idempotent-Replayed: true 付き)が返り、二重には作られません。エラーの応答(4xx)も同じものを返します。5xx は保存しないため、同じキーでやり直せます。
同じキーで本文が違う、または別のオブジェクト(別の Checkout Session の終了など)に使うと 409 idempotency_conflict、最初のリクエストの処理中に再送すると 409 request_in_progress です。キーは加盟店・エンドポイントごとに一意で、7 日間保存します。
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}'
# 同じキー・同じ本文で再送したとき
HTTP/1.1 201 Created
Idempotent-Replayed: trueMetadata
metadata は加盟店のキーと値の組で、20 個まで付けられます。キーは 1〜40 文字(英数字と _ . -)、値は 500 文字までの文字列です(数値は文字列に変換、null・空の文字列はキーを削除)。空でもオブジェクト({})で返します。
client_reference_id は加盟店の参照番号(注文番号など。200 文字まで)です。Checkout Session と決済の一覧をこれで絞り込めます。
どちらも Checkout Session・Payment Link に付けると決済に写り、決済・取引・返金の API と Webhook で返します。個人情報や秘密の値は入れないでください。
{
"client_reference_id": "order-1001",
"metadata": {
"customer_id": "c_42",
"plan": "premium"
}
}Webhook と署名
Webhook は payment.succeeded などのイベントを加盟店のサーバーへ知らせます。送信先は加盟店アカウントのオーナーが Merchant Console(APIキー)で登録します。5 件まで、インターネットから届く https:// の URL(ポート 443 または 8443)で、受け取るイベントの種類を選びます。署名のシークレット(whsec_…)は、送信先の作成時とシークレットの再発行時に一度だけ表示します。
RazPay は JSON の本文と次のヘッダーを付けて POST で送ります。
| ヘッダー | 説明 |
|---|---|
X-RazPay-Event-Id | イベントの ID(evt_…)。同じイベントの再送では同じです。 |
X-RazPay-Timestamp | この送信に署名した時刻(UNIX 秒)。 |
X-RazPay-Signature | v1= と、署名する文字列の HMAC-SHA256(16 進数)。鍵は署名のシークレットです。 |
Content-Type | application/json |
User-Agent | RazPay-Webhooks/1.0 |
署名の確かめ方
- 受け取った本文を、そのまま(JSON として読み込む前の文字列で)取り出します。
- 署名する文字列を作ります:
X-RazPay-Timestampの値、ピリオド(.)、本文をこの順につなげます。 - 送信先の署名のシークレット(
whsec_…の文字列全体)を鍵にして HMAC-SHA256 を計算し、小文字の 16 進数にして先頭にv1=を付けます。 X-RazPay-Signatureと、時間が一定の比較(hash_equals など)で比べます。違えば拒否します。- タイムスタンプがサーバーの時刻と 5 分以上ずれていれば拒否します(再送攻撃の対策)。
- 10 秒以内に 2xx を返してから処理してください。処理済みのイベント ID は無視します。
送信と再送
- 2xx の応答で成功です。タイムアウト・接続のエラー・
429・5xxのときは、約 1 分・5 分・30 分・2 時間・12 時間・24 時間後に再送します。そのほかの 4xx は再送しません(Merchant Console から再送できます)。 - リダイレクトは追いません。10 秒でタイムアウトします。
- 送信の順序は保証せず、同じイベントが 2 回以上届くことがあります。
resource_versionを使い、同じresource_idで処理済みのものより小さいresource_versionのイベントは無視してください。 - Merchant Console から送信先へ、種類
pingのテストのイベントを送れます。ping 以外のイベントは 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);
// 処理済みの $event['id'] は無視、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"
}
}
}イベントの種類
送信先ごとに、受け取るイベントの種類を Merchant Console で選びます。data は表のオブジェクトで、resource_id はその ID です。
| イベントの種類 | data | 説明 |
|---|---|---|
payment.succeeded | Payment | 決済が成功しました。このイベントの後に商品を提供してください。 |
payment.failed | Payment | 決済が失敗、または承認されませんでした。 |
transaction.pending_sale | Transaction | 成功した決済の取引ができました(まだ精算の対象ではありません)。 |
transaction.fulfillment | Transaction | 注文が発送・提供済みになりました。 |
transaction.actual_sale | Transaction | 取引が精算の対象になりました(お客様の受け取りの確認、設定した時間の経過、または RazPay による)。 |
transaction.on_hold | Transaction | 確認のため取引が保留になりました。 |
transaction.hold_released | Transaction | 保留が解除されました。 |
refund.requested | Transaction / 返金のイベントの data | 取消、または直接の返金が申請されました。 |
refund.recorded | 返金のイベントの data | お客様への直接の返金を加盟店が記録しました。 |
refund.rejected | Transaction | 取消の申請が認められませんでした。 |
refund.completed | Transaction / 返金のイベントの data | 取消、または直接の返金が完了しました。 |
refund.withdrawn | 返金のイベントの data | 直接の返金の申請が取り下げられました。 |
dispute.opened | Transaction | お客様が注文の問題を報告しました(取引は保留になります)。 |
dispute.resolved | Transaction | 報告された問題が解決し、保留が解除されました。 |
settlement.created | Settlement | 月ごとの精算ができました(下書き)。 |
settlement.confirmed | Settlement | 精算が確定しました(USDC の数量とレートを固定)。 |
settlement.reverted | Settlement | 送金の前に確定が取り消され、精算が下書きに戻りました(あらためて確定します)。 |
settlement.paid | Settlement | 支払いを送金しました(USDC・Polygon。txid が入ります)。 |
checkout_session.completed | Checkout Session | Checkout Session の支払いが成功しました。 |
checkout_session.expired | Checkout Session | Checkout Session が期限切れになりました(時間の経過、または API)。 |
レート制限
API キーごとに 1 分 120 回までです。認証したリクエストの応答には X-RateLimit-Limit(120)と X-RateLimit-Remaining が付きます。
超えると 429 rate_limited と Retry-After(待つ秒数)を返します。その秒数を待って再送してください。まとめて処理するときは間隔を空け、1 件ずつの取得ではなく一覧の絞り込みを使ってください。
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 Session
Checkout Session は、1 件の注文のための 1 回だけ使えるお支払い画面です。加盟店のサーバーで作成してお客様を url へ移し、Webhook の payment.succeeded または checkout_session.completed を受け取ってから商品を提供します。Web サイトからの決済におすすめの方法です。
Checkout Session を作成する
Create a Checkout Session
POST/v1/checkout-sessions
1 回だけ使えるお支払い画面(RazPay のホスト型決済ページ)を作成します。お客様を url へ移してください。product_id(と quantity)、または name と amount_minor を指定します。
必要なスコープ: checkout_sessions:write
パラメーター
-
Idempotency-Keystringヘッダー必須形式^[A-Za-z0-9_\-:.]{8,100}$
リクエストの本文 application/json
-
product_idstringProduct id (26 chars) -
namestringItem name shown on the payment page (required without product_id)最大文字数100 -
descriptionstring最大文字数1000 -
amount_minorintegerUnit price in minor units (required without product_id). The total (× quantity) must be within your minimum and maximum per payment最小100最大99999999 -
quantityinteger最小1最大999既定1 -
currencystringYour account currency. Other values are rejected値MYR, USD, AED -
display_currencystringReference display only値MYR, 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=最大文字数200 -
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)最大組数20キー^[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最大文字数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最大文字数2000 -
customerobjectPrefill the payment form. The customer can change name and phone. These values are never returned by the API or webhooks -
customer.namestring最大文字数100 -
customer.emailstring (email)最大文字数150 -
customer.phonestringInternational format recommended (+819012345678) -
customer.lock_emailbooleantrue = the email cannot be changed and only this email can pay (requires customer.email)既定false -
localestringLanguage of the payment page (default English; the customer can switch)値ja, en -
expires_atinteger | string (date-time)30 minutes to 7 days from now. Default: 24 hours -
auto_eligible_hoursinteger最小0最大168既定0
戻り値
Checkout Session オブジェクトを返します。
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
}Checkout Session を取得する
Retrieve a Checkout Session
GET/v1/checkout-sessions/{id}
必要なスコープ: checkout_sessions:read
パラメーター
-
idstringパス必須形式^[0-9a-z]{26}$
戻り値
Checkout Session オブジェクトを返します。
- 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
}Checkout Session の一覧
List Checkout Sessions
GET/v1/checkout-sessions
必要なスコープ: checkout_sessions:read
パラメーター
-
limitintegerクエリ最小1最大100既定10 -
starting_afterstringクエリId of the last object of the current page; returns older objects -
ending_beforestringクエリId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectクエリcreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringクエリ値open, complete, expired -
client_reference_idstringクエリ -
payment_idstringクエリ
戻り値
Checkout Session オブジェクトの一覧(List)を返します。
- 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"
}Checkout Session を終了する
Expire a Checkout Session
POST/v1/checkout-sessions/{id}/expire
open のセッションの受付を止めます(status は expired、url は null。Webhook checkout_session.expired)。complete・expired のときは 409 checkout_session_not_open、決済代行会社が支払いを処理している間は 409 checkout_session_in_progress です。
必要なスコープ: checkout_sessions:write
パラメーター
-
idstringパス必須形式^[0-9a-z]{26}$ -
Idempotency-Keystringヘッダー必須形式^[A-Za-z0-9_\-:.]{8,100}$
戻り値
Checkout Session オブジェクトを返します。
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 Link
Payment Link は、品目と金額を固定した RazPay のお支払い画面の URL です(回数の制限も可)。メール・チャット・QR コードで送れます。
Payment Link を作成する
Create a Payment Link
POST/v1/payment-links
必要なスコープ: payment_links:write
パラメーター
-
Idempotency-Keystringヘッダー必須形式^[A-Za-z0-9_\-:.]{8,100}$
リクエストの本文 application/json
Give product_id (+ quantity) or name + amount_minor.
-
product_idstringProduct id (26 chars) -
namestring最大文字数100 -
descriptionstring最大文字数1000 -
amount_minorintegerUnit price in minor units (1/100 of your account currency) when no product_id最小100最大99999999 -
quantityinteger最小1最大999既定1 -
currencystringYour account currency (set by the payment processor of your account). Other values are rejected値MYR, USD, AED -
display_currencystringReference display only; customers pay in your account currency値MYR, USD, AED, JPY -
expires_atstring (date-time) -
max_usesinteger1 = single use最小1 -
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)最小0最大168既定0 -
client_reference_idstringYour own reference (e.g. order number). Copied to the payments of this link最大文字数200 -
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)最大組数20キー^[A-Za-z0-9_.\-]{1,40}$
戻り値
Payment Link オブジェクトを返します。
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
}Payment Link を取得する
Retrieve a Payment Link
GET/v1/payment-links/{id}
必要なスコープ: payment_links:read
パラメーター
-
idstringパス必須形式^[0-9a-z]{26}$
戻り値
Payment Link オブジェクトを返します。
- 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
}Payment Link の一覧
List Payment Links
GET/v1/payment-links
すべての種類のリンク(API で作成したリンク・メールのリンク・商品ページ・請求書)。Checkout Session のリンクは含みません。
必要なスコープ: payment_links:read
パラメーター
-
limitintegerクエリ最小1最大100既定10 -
starting_afterstringクエリId of the last object of the current page; returns older objects -
ending_beforestringクエリId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectクエリcreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringクエリ値active, disabled
戻り値
Payment Link オブジェクトの一覧(List)を返します。
- 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"
}Payment Link を使えなくする
Deactivate a Payment Link
POST/v1/payment-links/{id}/deactivate
リンクを使えなくします。繰り返し呼び出すと同じリンクを返します。対象は API で作成したリンク(link)とメールのリンク(email)だけで、商品ページ・請求書のリンクは 409 payment_link_not_deactivatable です。
必要なスコープ: payment_links:write
パラメーター
-
idstringパス必須形式^[0-9a-z]{26}$ -
Idempotency-Keystringヘッダー必須形式^[A-Za-z0-9_\-:.]{8,100}$
戻り値
Payment Link オブジェクトを返します。
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)
商品は価格の決まった品目です。Checkout Session・Payment Link の作成で product_id に指定できます。
商品を作成する
Create a product
POST/v1/products
必要なスコープ: products:write
パラメーター
-
Idempotency-Keystringヘッダー必須形式^[A-Za-z0-9_\-:.]{8,100}$
リクエストの本文 application/json
-
namestring必須最大文字数100 -
descriptionstring最大文字数1000 -
kindstring値service, goods, other既定service -
price_minorinteger必須最小100最大99999999 -
currencystringYour account currency (set by the payment processor of your account). Other values are rejected値MYR, USD, AED -
display_currencystring値MYR, USD, AED, JPY
戻り値
商品(Product) オブジェクトを返します。
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}
必要なスコープ: products:read
パラメーター
-
idstringパス必須形式^[0-9a-z]{26}$
戻り値
商品(Product) オブジェクトを返します。
- 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
必要なスコープ: products:read
パラメーター
-
limitintegerクエリ最小1最大100既定10 -
starting_afterstringクエリId of the last object of the current page; returns older objects -
ending_beforestringクエリId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectクエリcreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
activebooleanクエリ
戻り値
商品(Product) オブジェクトの一覧(List)を返します。
- 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)
請求書は明細・税・支払期限を持ちます。発行した請求書には pay_url があり、bill_to_email を指定すると PDF を添付したメールを RazPay が送ります。
請求書を作成する(既定ですぐに発行)
Create (and by default issue) an invoice
POST/v1/invoices
必要なスコープ: invoices:write
パラメーター
-
Idempotency-Keystringヘッダー必須形式^[A-Za-z0-9_\-:.]{8,100}$
リクエストの本文 application/json
Send either items (line items; subtotal, tax and total are calculated) or amount_minor (one line, tax included).
-
bill_tostring必須最大文字数100 -
bill_to_emailstring (email)If set, the invoice is emailed when issued, with the PDF attached and the payment link -
bill_to_addressstring最大文字数500 -
descriptionstring最大文字数150 -
amount_minorintegerTax included. Required when items is not sent最小100最大99999999 -
itemsarray of object最小件数1最大件数20 -
items[].descriptionstring必須最大文字数191 -
items[].quantityinteger必須最小1最大100000 -
items[].unit_price_minorinteger必須最小0 -
tax_rate_bpintegerTax rate in basis points (600 = 6%). Tax = subtotal × rate, rounded to the nearest minor unit (1/100)最小0最大10000既定0 -
currencystringYour account currency (set by the payment processor of your account). Other values are rejected値MYR, USD, AED -
issue_datestring (date) -
due_datestring (date)必須 -
notesstring最大文字数1000 -
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)最小0最大168既定0 -
issueboolean既定true -
localestring値en, ja
戻り値
請求書(Invoice) オブジェクトを返します。
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}
必要なスコープ: invoices:read
パラメーター
-
idstringパス必須形式^[0-9a-z]{26}$
戻り値
請求書(Invoice) オブジェクトを返します。
- 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
必要なスコープ: invoices:read
パラメーター
-
limitintegerクエリ最小1最大100既定10 -
starting_afterstringクエリId of the last object of the current page; returns older objects -
ending_beforestringクエリId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectクエリcreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringクエリ値draft, issued, paid, void, refunded
戻り値
請求書(Invoice) オブジェクトの一覧(List)を返します。
- 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)
決済は、お客様が Checkout Session・Payment Link・請求書を支払う 1 回ごとの記録です。status が psp_success の決済だけが取引になります。
決済を取得する
Retrieve a payment
GET/v1/payments/{id}
必要なスコープ: payments:read
パラメーター
-
idstringパス必須形式^[0-9a-z]{26}$
戻り値
決済(Payment) オブジェクトを返します。
- 200 OK
- 404 Error — Error
レスポンスの項目
-
idstring -
order_idstring -
statusstring値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常に"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)最大組数20キー^[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
必要なスコープ: payments:read
パラメーター
-
limitintegerクエリ最小1最大100既定10 -
starting_afterstringクエリId of the last object of the current page; returns older objects -
ending_beforestringクエリId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectクエリcreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringクエリ値created, payment_pending, psp_processing, psp_success, failed, cancelled -
client_reference_idstringクエリ
戻り値
下の項目のオブジェクトを返します。
- 200 OK
- 422 Error — Error
レスポンスの項目
-
objectstring常に"list" -
dataarray of Payment -
data[].idstring -
data[].order_idstring -
data[].statusstring値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常に"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)最大組数20キー^[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)
取引は成功した決済で、精算までの状態を持ちます。取引の ID は決済の ID と同じです。
取引を取得する(ID は決済の ID)
Retrieve a transaction (id = payment id)
GET/v1/transactions/{id}
必要なスコープ: transactions:read
パラメーター
-
idstringパス必須形式^[0-9a-z]{26}$
戻り値
取引(Transaction) オブジェクトを返します。
- 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
取引の ID は決済の ID です。starting_after・ending_before にも決済の ID を指定します。
必要なスコープ: transactions:read
パラメーター
-
limitintegerクエリ最小1最大100既定10 -
starting_afterstringクエリId of the last object of the current page; returns older objects -
ending_beforestringクエリId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectクエリcreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringクエリsale_status値pending_sale, fulfillment, actual_sale, cancelled
戻り値
取引(Transaction) オブジェクトの一覧(List)を返します。
- 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 a direct refund of a payment
POST/v1/refunds
動きは決済の決済代行会社によって変わります。(1) 取消ができる決済代行会社:取消の申請です。202 で受け付け、RazPay が決済代行会社で取り消した後に refund.completed(できなければ refund.rejected)を送ります。決済代行会社の取消可能期間内だけ申請でき、過ぎると 409 cancellation_period_passed です。精算に入った後なら、その支払額を後の精算から差し引きます。一部の取消はできません。202 の本文に id・type はありません。(2) 取消ができない決済代行会社:直接の返金(type direct)を作成します。売上・精算はそのままで、加盟店がお客様へ直接返金し、Merchant Console で記録します。一部の額も指定できます(返金できる残りの額まで。超えると 422 amount_invalid)。Webhook:refund.requested、refund.recorded(加盟店が返金を記録)、refund.completed、refund.withdrawn(申請の取り下げ)。202 の本文は返金(id・type・status・amount_minor・currency・reason・due_on・refunded_on・method・created_at)と取引です。
必要なスコープ: refunds:write
パラメーター
-
Idempotency-Keystringヘッダー必須形式^[A-Za-z0-9_\-:.]{8,100}$
リクエストの本文 application/json
-
payment_idstring必須 -
amount_minorintegerOptional. Cancellation: must equal the payment amount. Direct refund: 1 to the remaining refundable amount (default: all) -
reasonstring必須最大文字数1000
戻り値
下の項目のオブジェクトを返します。
レスポンスの項目
-
objectstring常に"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 request値direct -
payment_idstring -
statusstringAlways requested in this response. Later states of a direct refund (webhook data.refund.status): refunded, completed, cancelled値requested -
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 recorded値bank_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}
必要なスコープ: refunds:read
パラメーター
-
idstringパス必須形式^[0-9a-z]{26}$
戻り値
返金(Refund) オブジェクトを返します。
- 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
直接の返金(type direct)の一覧です。取消ができる決済代行会社の取消の申請は、取引の refund_status で確認してください。
必要なスコープ: refunds:read
パラメーター
-
limitintegerクエリ最小1最大100既定10 -
starting_afterstringクエリId of the last object of the current page; returns older objects -
ending_beforestringクエリId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectクエリcreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringクエリ値requested, refunded, completed, cancelled -
payment_idstringクエリ
戻り値
返金(Refund) オブジェクトの一覧(List)を返します。
- 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"
}Voucher
成功したすべての決済に Voucher(購入の公開の参照)があります。
Voucher を取得する
Retrieve a voucher
GET/v1/vouchers/{id}
必要なスコープ: vouchers:read
パラメーター
-
idstringパス必須形式^[0-9a-z]{26}$
戻り値
Voucher オブジェクトを返します。
- 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)
精算は月ごとの支払いです。月末締め(日本時間)・翌月末に USDC(Polygon)で支払います。
精算の一覧(新しい順)
List settlements (newest first)
GET/v1/settlements
必要なスコープ: settlements:read
パラメーター
-
limitintegerクエリ最小1最大100既定25 -
starting_afterstringクエリId of the last object of the current page; returns older objects -
ending_beforestringクエリId of the first object of the current page; returns newer objects. Not together with starting_after -
createdobjectクエリcreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
statusstringクエリ値draft, confirmed, paid
戻り値
精算(Settlement) オブジェクトの一覧(List)を返します。
- 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)
Webhook の送信先へ送るものと同じイベントです。受け取れなかった送信の照合に使えます。
イベントを取得する
Retrieve an event
GET/v1/events/{id}
必要なスコープ: events:read
パラメーター
-
idstringパス必須形式^evt_[0-9a-z]{26}$
戻り値
イベント(Event) オブジェクトを返します。
- 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
Webhook と同じイベントを新しい順に返します(Webhook の送信先が無くても記録します)。受け取れなかった Webhook の照合に使ってください。接続確認の ping は含みません。
必要なスコープ: events:read
パラメーター
-
limitintegerクエリ最小1最大100既定10 -
starting_afterstringクエリ形式^evt_[0-9a-z]{26}$ -
ending_beforestringクエリ形式^evt_[0-9a-z]{26}$ -
createdobjectクエリcreated[gte], created[gt], created[lte], created[lt]: Unix seconds or ISO 8601 (UTC if no offset) -
typestringクエリExact type, or a prefix ending with .* (e.g. payment.*) -
resource_idstringクエリ
戻り値
イベント(Event) オブジェクトの一覧(List)を返します。
- 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"
}オブジェクト
Checkout Session
-
idstring -
objectstring常に"checkout_session" -
urlstring (uri) | nullRazPay hosted payment page. null when the session is no longer open -
statusstring値open, complete, expired -
payment_statusstring値unpaid, 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)最大組数20キー^[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 | null値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
{
"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値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常に"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)最大組数20キー^[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 confirmed値pending_sale, fulfillment, awaiting_settlement, settled, cancelled, refunded, on_hold -
settlement_statusstring値not_eligible, awaiting_settlement, settlement_confirmed, excluded -
sale_statusstring値pending_sale, fulfillment, actual_sale, cancelled -
holdstring | null値cancel_requested, dispute, manual_review, null -
refund_statusstring | null値requested, 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 -
objectstring常に"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)最大組数20キー^[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)
-
objectstring常に"refund" -
idstring -
payment_idstring -
typestring値direct -
statusstring値requested, refunded, completed, cancelled -
amount_minorinteger -
currencystring -
reasonstring | null -
due_onstring (date) | null -
refunded_onstring (date) | null -
methodstring | null値bank_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)最大組数20キー^[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 -
objectstring常に"payment_link" -
urlstring (uri) -
namestring -
descriptionstring | null -
amount_minorinteger -
currencystring -
display_currencystring -
quantityinteger -
product_idstring | null -
statusstring値active, disabled -
usableboolean -
statestring値ok, 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 = invoice値link, 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)最大組数20キー^[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 -
objectstring常に"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 -
objectstring常に"invoice" -
invoice_numberstring -
statusstring値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_minorintegerTotal (tax included) -
currencystring -
localestring値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
{
"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値draft, 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)値USDC -
payout_networkstringNetwork the payout is sent on (always polygon)値polygon -
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 -
objectstring常に"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 -
statusstring値reserved, 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 -
objectstring常に"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)
Events API で返します。Webhook の本文は、ここから object・created_at・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.値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値test, 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 -
objectstring常に"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
}返金のイベントの data
直接の返金の refund.* イベントの data です。
-
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)最大組数20キー^[A-Za-z0-9_.\-]{1,40}$ -
refundobject -
refund.objectstring常に"refund" -
refund.idstring -
refund.payment_idstring -
refund.typestring値direct -
refund.statusstring値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値bank_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)
一覧のエンドポイントはすべてこの形で返します。data に新しい順でオブジェクトが入ります。
-
objectstring常に"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
Checkout Session・Payment Link に付ける加盟店のキーと値の組で、その決済に写ります。
{
"customer_id": "c_42"
}エラー(Error)
エラーの応答はすべてこの本文です。処理の分岐は error.code で行ってください(error.message は人が読むための文です)。
-
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"
}