本文へ移動
RazPay. API リファレンス

RazPay API v1.0

API リファレンス

RazPay API は HTTPS の REST API です。リクエストとレスポンスは JSON(UTF-8)で、すべてのリクエストを加盟店アカウントの API キーで認証します。日時は UTC の ISO 8601 です。

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

OpenAPI 3.1(YAML) OpenAPI 3.1(JSON)

はじめに

お支払いは必ず 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 の値は改行とタブだけ使えます)。前後の空白は取り除きます。

基本の流れ

  1. 加盟店のサーバーで Checkout Session を作成します(POST /checkout-sessions)。品目・金額・注文番号(client_reference_id)・success_url・cancel_url を指定します。
  2. お客様をセッションの url へ移します。お客様は情報を入力し、決済代行会社の画面で支払います。
  3. Webhook の payment.succeeded を受け取り、署名を確かめてから商品を提供します。success_url への移動は補助です(それだけを頼りにしないでください)。
  4. 売上は取引(Transactions)API、月ごとの支払いは精算(Settlements)API で確認できます。
リクエストの例 · 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"
    }'

認証

API キーを Authorization ヘッダーの Bearer トークンとして送ります。キーの接頭辞は、本番が rz_live_、テスト環境が rz_test_ です。もう一方の環境のキーは 401 unauthorized になります。

キーは加盟店アカウントのオーナーが Merchant Console(APIキー)で作成します。キーは作成したときに一度だけ表示し、RazPay はハッシュだけを保存します。有効なキーは 10 個まで持て、いつでも失効できます。

キーごとにスコープ(権限)があります。キーに無いスコープの操作は 403 insufficient_scope です。システムごとに必要なスコープだけを付けてください。

キーは加盟店のサーバーに置き、Web ページ・スマホアプリ・公開のリポジトリには入れないでください。

スコープできること
payments:read決済の照会・一覧
payment_links:readPayment Link の照会・一覧
payment_links:writePayment Link の作成・停止
products:write商品の作成
invoices:write請求書の作成・発行
refunds:write取消・直接の返金の申請
transactions:read取引の照会・一覧
vouchers:readVoucher の照会
settlements:read精算の一覧
checkout_sessions:readCheckout Session の照会・一覧
checkout_sessions:writeCheckout 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意味
unauthorizedAPI キーが無い、正しくない・失効した、またはもう一方の環境のキーです。
insufficient_scopeキーにエンドポイントのスコープがありません。
not_foundオブジェクトまたはエンドポイントがありません(他の加盟店のものを含む)。
validation_failed入力に誤りがあります。error.fields を確認してください。
invalid_jsonリクエストの本文が正しい JSON のオブジェクトではありません。
idempotency_key_requiredPOST に正しい 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_openCheckout Session はすでに完了または期限切れです。
checkout_session_in_progressCheckout Session の支払いを処理中です。
payment_link_not_deactivatable商品ページ・請求書のリンクは停止できません。
method_not_allowedこのエンドポイントでは使えない HTTP メソッドです。
internal_errorRazPay 側のエラーです。時間をおいて再送し、続く場合は request_id を添えてお問い合わせください。
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"
}

一覧とページ送り

一覧は {"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: true

Metadata

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-Signaturev1= と、署名する文字列の HMAC-SHA256(16 進数)。鍵は署名のシークレットです。
Content-Typeapplication/json
User-AgentRazPay-Webhooks/1.0

署名の確かめ方

  1. 受け取った本文を、そのまま(JSON として読み込む前の文字列で)取り出します。
  2. 署名する文字列を作ります:X-RazPay-Timestamp の値、ピリオド(.)、本文をこの順につなげます。
  3. 送信先の署名のシークレット(whsec_… の文字列全体)を鍵にして HMAC-SHA256 を計算し、小文字の 16 進数にして先頭に v1= を付けます。
  4. X-RazPay-Signature と、時間が一定の比較(hash_equals など)で比べます。違えば拒否します。
  5. タイムスタンプがサーバーの時刻と 5 分以上ずれていれば拒否します(再送攻撃の対策)。
  6. 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
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);
// 処理済みの $event['id'] は無視、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);
});
イベントの本文 · 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"
    }
  }
}

イベントの種類

送信先ごとに、受け取るイベントの種類を Merchant Console で選びます。data は表のオブジェクトで、resource_id はその ID です。

イベントの種類data説明
payment.succeededPayment決済が成功しました。このイベントの後に商品を提供してください。
payment.failedPayment決済が失敗、または承認されませんでした。
transaction.pending_saleTransaction成功した決済の取引ができました(まだ精算の対象ではありません)。
transaction.fulfillmentTransaction注文が発送・提供済みになりました。
transaction.actual_saleTransaction取引が精算の対象になりました(お客様の受け取りの確認、設定した時間の経過、または RazPay による)。
transaction.on_holdTransaction確認のため取引が保留になりました。
transaction.hold_releasedTransaction保留が解除されました。
refund.requestedTransaction / 返金のイベントの data取消、または直接の返金が申請されました。
refund.recorded返金のイベントの dataお客様への直接の返金を加盟店が記録しました。
refund.rejectedTransaction取消の申請が認められませんでした。
refund.completedTransaction / 返金のイベントの data取消、または直接の返金が完了しました。
refund.withdrawn返金のイベントの data直接の返金の申請が取り下げられました。
dispute.openedTransactionお客様が注文の問題を報告しました(取引は保留になります)。
dispute.resolvedTransaction報告された問題が解決し、保留が解除されました。
settlement.createdSettlement月ごとの精算ができました(下書き)。
settlement.confirmedSettlement精算が確定しました(USDC の数量とレートを固定)。
settlement.revertedSettlement送金の前に確定が取り消され、精算が下書きに戻りました(あらためて確定します)。
settlement.paidSettlement支払いを送金しました(USDC・Polygon。txid が入ります)。
checkout_session.completedCheckout SessionCheckout Session の支払いが成功しました。
checkout_session.expiredCheckout SessionCheckout Session が期限切れになりました(時間の経過、または API)。

レート制限

API キーごとに 1 分 120 回までです。認証したリクエストの応答には X-RateLimit-Limit(120)と X-RateLimit-Remaining が付きます。

超えると 429 rate_limited と Retry-After(待つ秒数)を返します。その秒数を待って再送してください。まとめて処理するときは間隔を空け、1 件ずつの取得ではなく一覧の絞り込みを使ってください。

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 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_idstring
    Product id (26 chars)
  • namestring
    Item name shown on the payment page (required without product_id)
    最大文字数 100
  • descriptionstring
    最大文字数 1000
  • amount_minorinteger
    Unit 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
  • currencystring
    Your account currency. Other values are rejected
    値 MYR, USD, AED
  • display_currencystring
    Reference display only
    値 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=
    最大文字数 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)
    最大組数 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
  • customerobject
    Prefill 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.phonestring
    International format recommended (+819012345678)
  • customer.lock_emailboolean
    true = the email cannot be changed and only this email can pay (requires customer.email)
    既定 false
  • localestring
    Language 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"
    }'
レスポンスの例 · 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
}

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_…"
レスポンスの例 · 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
}

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_…"
レスポンスの例 · 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"
}

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"
レスポンスの例 · 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)

商品は価格の決まった品目です。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
  • currencystring
    Your 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"
    }'
レスポンスの例 · 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}

必要なスコープ: 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_…"
レスポンスの例 · 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

必要なスコープ: 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_…"
レスポンスの例 · 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)

請求書は明細・税・支払期限を持ちます。発行した請求書には 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_minorinteger
    Tax 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_bpinteger
    Tax rate in basis points (600 = 6%). Tax = subtotal × rate, rounded to the nearest minor unit (1/100)
    最小 0最大 10000既定 0
  • currencystring
    Your 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_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)
    最小 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"
    }'
レスポンスの例 · 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}

必要なスコープ: 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_…"
レスポンスの例 · 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

必要なスコープ: 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_…"
レスポンスの例 · 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)

決済は、お客様が 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 | 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)
    最大組数 20キー ^[A-Za-z0-9_.\-]{1,40}$
  • transactionTransaction | null
リクエストの例
curl https://www.raz-pay.com/api/v1/payments/01jbz6x0d3k8h2m5n7p9q4r6s8 \
  -H "Authorization: Bearer rz_live_…"
レスポンスの例 · 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

必要なスコープ: 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 | 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)
    最大組数 20キー ^[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
リクエストの例
curl "https://www.raz-pay.com/api/v1/payments?limit=3" \
  -H "Authorization: Bearer rz_live_…"
レスポンスの例 · 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)

取引は成功した決済で、精算までの状態を持ちます。取引の 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_…"
レスポンスの例 · 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

取引の 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_…"
レスポンスの例 · 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 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_minorinteger
    Optional. Cancellation: must equal the payment amount. Direct refund: 1 to the remaining refundable amount (default: all)
  • reasonstring必須
    最大文字数 1000

戻り値

下の項目のオブジェクトを返します。

レスポンスの項目
  • objectstring
    常に "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
    値 direct
  • payment_idstring
  • statusstring
    Always requested in this response. Later states of a direct refund (webhook data.refund.status): refunded, completed, cancelled
    値 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
    値 bank_transfer, crypto_wallet, cash, other, null
  • created_atstring (date-time)
    Direct refund only
  • livemodeboolean
    Direct 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"
    }'
レスポンスの例 · 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}

必要なスコープ: 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_…"
レスポンスの例 · 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

直接の返金(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_…"
レスポンスの例 · 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"
}

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_…"
レスポンスの例 · 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)

精算は月ごとの支払いです。月末締め(日本時間)・翌月末に 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_…"
レスポンスの例 · 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)

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_…"
レスポンスの例 · 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

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_…"
レスポンスの例 · 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"
}

オブジェクト

Checkout Session

  • idstring
  • objectstring
    常に "checkout_session"
  • urlstring (uri) | null
    RazPay hosted payment page. null when the session is no longer open
  • statusstring
    値 open, complete, expired
  • payment_statusstring
    値 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)
    最大組数 20キー ^[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
    値 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
例 · 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
    値 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 | 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)
    最大組数 20キー ^[A-Za-z0-9_.\-]{1,40}$
例 · 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
    値 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) | 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
    常に "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)
    最大組数 20キー ^[A-Za-z0-9_.\-]{1,40}$
例 · 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
    常に "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
  • 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)
    最大組数 20キー ^[A-Za-z0-9_.\-]{1,40}$
例 · 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
    常に "product"
  • namestring
  • descriptionstring | null
  • kindstring
  • price_minorinteger
  • currencystring
  • display_currencystring
  • activeboolean
  • created_atstring (date-time)
  • livemodeboolean
例 · 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
    常に "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_minorinteger
    Total (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
例 · 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
    値 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)
    値 USDC
  • payout_networkstring
    Network the payout is sent on (always polygon)
    値 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
    常に "settlement"
  • created_atstring (date-time)
  • livemodeboolean
例 · 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
    値 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
    常に "voucher"
  • created_atstring (date-time)
  • livemodeboolean
例 · 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)

Events API で返します。Webhook の本文は、ここから object・created_at・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.
    値 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_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
    常に "event"
  • created_atstring (date-time)
  • livemodeboolean
例 · 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
}

返金のイベントの data

直接の返金の refund.* イベントの data です。

  • 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)
    最大組数 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
例 · 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)

一覧のエンドポイントはすべてこの形で返します。data に新しい順でオブジェクトが入ります。

  • objectstring
    常に "list"
  • dataarray of any
  • has_moreboolean
    true if there are more objects in the direction you paginate
  • urlstring
例 · List
{
  "object": "list",
  "data": [],
  "has_more": false,
  "url": "/v1/payments"
}

Metadata

Checkout Session・Payment Link に付ける加盟店のキーと値の組で、その決済に写ります。

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

エラー(Error)

エラーの応答はすべてこの本文です。処理の分岐は error.code で行ってください(error.message は人が読むための文です)。

  • errorobject
  • error.codestring
  • error.messagestring
    Human-readable message. English by default; Japanese when the request sends Accept-Language: ja
  • error.fieldsobject
  • request_idstring
例 · 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"
}