決済

Fast Track 決済

この方法を選ぶと、ウィジェットを組み込む必要も、決済に関する他のセクションに従う必要もありません。POST を 1 回呼び出すだけで決済 URL が返され、結果が OK または KO になると Wealthreader がお客様のサーバーに通知します。予備の手段として、応答の payment_intent_id を保存してください。通知が届かない場合でも、これを使って状態を照会できます。

支払人はその URL を開き、自分の銀行で承認します。内部では API の他の部分と同じ変更不能なインテントが作成されます。金額、受取人、振込内容はブラウザーに届く前に固定され、呼び出しが途中で切れても Idempotency-Key ヘッダーによって二重請求が防がれます。

決済の作成

POST /payments/?action=fast-track

必須ヘッダーは Content-Type: application/json、X-API-Key、Idempotency-Key です。このキーは 16 ～ 128 文字で、先頭は英字または数字でなければならず、使用できるのは英字、数字、. _ : - のみです。UUID v4 も使用できます。キーがない場合や長さが無効な場合、応答は 400 idempotency_key_required です。それ以外の文字を使用した場合は 422 invalid_customer_reference です。このキーは加盟店の参照番号も兼ねるため、本文で送信する必要はありません。同じキーを同じ本文で再送すると、同じ URL が再び返されます。異なるデータで同じキーを再利用すると、応答は 409 idempotency_conflict です。

フィールド	型	説明
`amount`	文字列	主単位の金額を JSON 文字列で指定します。`"15.50"` は 15.50 を表します。小数部のない整数（`"15"`）も使用できます。小数は最大 2 桁で、`"15.5"` と `"15.50"` は同じ金額です。最小値は `0.01` です。最大値は、各顧客が自分の銀行で設定している上限によって制限されます。これらの形式ルールに合わない場合は `422 invalid_amount` になります。
`currency`	文字列	ISO 4217 通貨コード。このバージョンでは `EUR` です。
`beneficiary`	オブジェクト	受取人。`name`（1 ～ 140 文字）と `iban`（スペースなし、チェックディジット付き）を指定します。
`reference`	文字列	銀行明細に表示される振込内容。最大 140 文字です。
`priority`	文字列	`normal` または `instant`。
`notification_url`	文字列	OK または KO を通知する公開 `https` URL。
`logo`	文字列	任意。SVG 形式の加盟店ロゴの公開 `https` URL です。パスは `.svg` で終わる必要があり（クエリパラメーターは使用可）、認証情報やプライベートアドレスを含めず、ASCII 文字で最大 2048 文字とします。決済ページでは、受取人名の横、概要の上に表示されます。`logo` がない場合、加盟店のヘッダーは表示されません。Wealthreader はこの URL をダウンロードせず、支払人のブラウザーが読み込みます。それ以外の値は `422 invalid_logo` になります。

logo 以外のフィールドはすべて必須です。本文は許可リスト方式です。余分なフィールドがある場合や必須フィールドが欠けている場合は 422 invalid_request になります。logo は決済の一部です。同じ Idempotency-Key で異なる logo を指定した場合も 409 idempotency_conflict になります。

即時送金には、この API 独自の上限はありません。銀行は受け付けられない送金を金額を理由とする場合も含めて拒否し、その拒否は KO として notification_url に届きます。

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"
: "${WR_PAYMENT_IDEMPOTENCY_KEY:?Genere un UUID v4 para este pago}"

curl --request POST 'https://api.wealthreader.com/payments/?action=fast-track' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "amount": "15.50",
    "currency": "EUR",
    "beneficiary": {
      "name": "Comercio Online S.L.",
      "iban": "ES9121000418450200051332"
    },
    "reference": "Pedido 78901",
    "priority": "normal",
    "notification_url": "https://tienda.example.com/pagos/aviso",
    "logo": "https://tienda.example.com/marca/logo.svg"
  }'

応答は、初回は 201、キーがすでに存在していた場合は 200 で、URL と決済の識別子を含みます。

{
  "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…&api_origin=https%3A%2F%2Fapi.wealthreader.com",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

支払人をその URL にリダイレクトしてください。トークンはフラグメントに含まれ、ウィジェットと同時に（通常は 15 分で）有効期限が切れます。ログには記録しないでください。payment_intent_id は注文と一緒に保存してください。

OK または KO の通知

Wealthreader が決済の状態を確認して最終状態であると判断すると、POST を notification_url に送信します。その際、Content-Type: application/json と User-Agent: WealthReader-Payments を指定します：

{
  "outcome": "ok",
  "payment_status": "settled",
  "customer_reference": "11111111-1111-4111-8111-111111111111",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

outcome が ok になるのは、銀行が資金決済を完了した（settled）場合だけです。rejected、cancelled、expired、failed は ko として通知されます。判定できない結果（reconciliation_required）は最終状態ではないため、通知されません。
customer_reference はお客様の Idempotency-Key、payment_intent_id は決済作成時に返された識別子です。
通知を配信済みとするには 2xx で応答してください。Wealthreader の待機時間は最大 3 秒で、リダイレクトには従いません。
同じ通知が複数回届くことがあります。customer_reference と outcome の組み合わせを冪等に扱ってください。
公開 https 以外の URL は決済作成時に拒否され、送信のたびに再確認されます。

通知のタイミング。 状態の確認は、支払人が決済ページにいる間（ページは最終結果が出るか決済セッションの有効期限が切れるまで状態を照会し続けます）と、お客様が POST /payments/?action=status で照会するたびに行われます。別途スケジュールされた送信はありません。銀行の処理が完了する前に支払人がページを閉じた場合や、お客様のサーバーが 2xx で応答しなかった場合、通知は次回の確認時に送信されます。そのため、支払人をリダイレクトしてから数分たっても通知が届かない場合は、payment_intent_id で状態を照会してください。この照会によって保留中の通知も送信されます。状態、ポーリング、照合を参照してください。

通知には署名がありません。 価値の高い商品やサービスを引き渡す前に、POST /payments/?action=status で結果を確認してください。その際、お客様の X-API-Key と payment_intent_id を使用します。資金決済の確認とみなせるのは、その応答の payment_status: settled だけです。

最終更新 2026-11-08