決済

支払い意図と冪等性

支払い意図は、ユーザーがウィジェットとやり取りする前に取引の経済条件を不変に設定します。これにより、悪意のあるクライアントがフロントエンドで金額、宛先口座、または送金の概念を改ざんするのを防ぎます。

支払い意図を作成するためのパラメータ(`POST /payments/?action=create`)

1. 加盟店向け標準モデル(自己受益者)

このモデルでは、加盟店はすべての収集データを定義します:

フィールド	種類	必須	説明とルール
`amount_minor`	整数	はい	より小さい単位(セント)で表示される金額。例えば、 `1500` は `15,00 EUR`を表します。
`currency`	テキスト文字列	はい	ISO 4217 3文字通貨コード。現在 `EUR`。
`beneficiary`	JSON データオブジェクト	はい	宛先アカウントデータ: `name` (所有者、1〜140文字のテキスト)と `iban` (空白なしの有効な有効IBAN でチェックデジットの検証済み)。この2つのキーのみをサポートしています。
`reference`	テキスト文字列	はい	銀行取引明細書に概念が見える(テキスト最大140文字)。
`customer_reference`	テキスト文字列	はい	注文または顧客の内部識別子(テキストの1〜128文字:文字、数字、 `.`、 `_`、 `:`、 `-`;必ず文字または数字で始まらなければなりません)。
`allowed_origin`	テキスト文字列	はい	ウィジェットを埋め込む正確な HTTPS ソース(例: `https://tienda.example.com`)で、パスなし。
`allowed_institution_codes`	データアレイ	いいえ	許可されたエンティティコードの一覧(例: `["santander-es", "bbva-es"]`)。省略された場合、カタログ内の任意のエンティティが許可されます。
`locale`	テキスト文字列	いいえ	ウィジェットインターフェースの言語。このリリースで受け入れられているのは `es`のみです。その他の値は `422 invalid_locale`返します。
`expected_mode`	テキスト文字列	いいえ	`mock` または `live`。期待される環境を呼んでいるかどうかを確認します。環境は変わりません。一致しなければ `409 payment_mode_mismatch`。

本体は 厳密なホワイトリストです。このテーブルに含まれないフィールドを送信すると 422 invalid_request返し、必須のフィールドを省略すると同様に返されます。 Content-Type: application/json ヘッダーは必須(415 json_required)で、本体は32KBに制限されています。

2. 管理プロファイルを持つモデル(寄付/デモ)

規制されたケースや cruz_roja_demoのような公開デモンストレーションでは、サーバーが財務ルールを課し、公式の目標口座を設定します。

フィールド	種類	必須	説明とルール
`profile`	テキスト文字列	はい	プロファイル識別子(例: `cruz_roja_demo`)。
`institution_code`	テキスト文字列	はい	ユーザー選択エンティティコード( `profile-institutions`より)。
`amount_minor`	整数	はい	プロフィールポリシーによって制限される金額(例:1セントから100セント)。
`customer_reference`	テキスト文字列	はい	あなたのシステム自身の監査用参照識別子です。
`allowed_origin`	テキスト文字列	はい	ウィジェット HTTPS ソース。
`locale`	テキスト文字列	いいえ	ウィジェット言語(`es`)。
`expected_mode`	テキスト文字列	いいえ	期待モード(`mock` または `live`)。

profileが指定されると、サーバーは自動的に公式の受取人と対応する概念を割り当てます。管理プロファイルでリクエストに対してbeneficiaryやreferenceを送信しないでください。

`Idempotency-Key`の法則

Idempotency-Keyヘッダーは、支払い意図を作成するために任意のリクエストで必須です。16文字から128文字の可視ASCIIテキストを含み、空白を含めてはいけません(例:v4 UUID)。その範囲は認証済み企業ごとに固有のものです:

同じ冪等キーと同じ本体: 以前に作成された元の意図を idempotent_replay: trueと共に返します。新たなチャージは発生せず、銀行の注文も重複しません。
同じ冪等性キーで異なるリクエスト本文: 即座に反応する HTTP 409 Conflict。
同じ冪等性キーは別の会社で 、完全に孤立した冪等性空間に属しています。

決済インテントの作成でネットワーク障害やタイムアウトが発生した場合は、まったく同じ Idempotency-Key ヘッダーと同じリクエスト本文で再試行してください。一時的なエラーで新しいキーを生成しないでください。

持続性とライフサイクル

事前の永続性: 意図は応答を返す前にデータベースに記録され、銀行コネクターとやり取りする前に行われます。
一時的なウィジェットトークン: レスポンス token (payment.widget.token)は有効時間が短く(通常15〜30分)、宣言された allowed_origin からのみ使用可能です。
並行ロック: システムは楽観制御と leases 制御を実装し、同時に2つの通話が同じ意図を承認または変更するのを防ぎます。

一般的なエラーコード

HTTP	コード	原因	推奨される行動
`400`	`idempotency_key_required`	`Idempotency-Key`ヘッダーが欠落しているか、フォーマットが誤っています。	16文字から128文字のASCIIテキストの有効なキーを生成し、スペースを除きます。
`409`	`idempotency_conflict`	キーは支払いの詳細が変わって再利用されています。	異なる支払いのために新しいキーを作成したり、完全に同じリクエスト本文を再利用したりしましょう。
`409`	`payment_mode_mismatch`	`expected_mode` 、あなたが呼んでいる環境のモードとは一致しません。	サンドボックスを目指すのか本番環境を目指しているのか確認してください。モードは通話ではなく展開によって設定されます。
`401`	`invalid_api_key`	`X-API-Key`ヘッダーが欠損している、フォーマットが無効であるか、パスキーが存在しないか非アクティブである場合もあります。	パスコードを確認しましょう。フロントエンドには絶対に含めないでください。
`403`	`payments_not_allowed`	APIキーにはプロダクト`PAYMENTS`有効化されていません。	アカウント Wealth Reader 支払いを有効にするにはサポートに連絡してください。
`403`	`payment_profile_not_allowed`	管理プロファイルはあなたの会社では有効になっていません。	Wealth Readerからプロフィールアカウント登録をリクエストしてください。
`429`	`api_limit_reached`	パスコードは累積通話カウンターを使い果たしました。	再試行や待機で解決するものではありません。ウィンドウや自動リセットはありません。制限延長を申請してください。
`415`	`json_required`	`Content-Type: application/json`のヘッダーがありません。	リクエスト本文を JSON として送信してください。
`422`	`invalid_request`	必須フィールドが欠落しているか、認識されていないフィールドが提出されています。	パラメータテーブルを確認してください:本体は厳密なホワイトリストです。
`422`	`invalid_institution`	選択した事業体は利用不可または無効です。	有効なコードについては `GET /payments/entities/` を参照してください。
`422`	`invalid_amount`	金額は最低値(€0.01)より少ない場合、または整数ではありません。	整数をセント単位で送っているか確認してください(`amount_minor`)。

次のステップ

続きをステータス、定期的なステータス協議および調整.

最終更新 2026-09-10

支払い意図を作成するためのパラメータ(POST /payments/?action=create)