Webhook
このページでは、弊社後払い決済サービスからのイベント通知を受け取るための Webhook 設定と運用の要点を説明します。
目的
弊社後払い決済サービスでは、購入者がアクセスしているページで立ち上げた、決済モーダルの上で取引情報や与信結果のデータをやり取りします。 フロントエンドでのデータのやり取りとなるため、購入者のデバイスの通信断等により加盟店様 EC システムと弊社システムの間で適切にデータを連携できない場合があります。
そのため、認証成功時や決済成功時にバックエンドでデータの登録・更新をお知らせする Webhook(通知)の機能を用意しています。 事前に通知先の URL を登録しておくことで、認証処理や決済処理の完了時に設定 URL へ弊社システムから決まった POST リクエストを送信します。
加盟店様 EC システムにて、通知を受け取ったあとにデータの整合性を検証する処理を実装してください。 検証の結果、通知されたデータと加盟店様 EC システムにて保存しているデータに不整合がある場合、 弊社システムへ全額課金払戻の処理を行うなど、データ不整合を解消する処理を行ってください。
決済成功時に通信断が発生した場合、加盟店様 EC システム：未処理 atone システム：処理済 というデータ不整合状態が発生します。誤請求に繋がる可能性がありますので、決済成功 Webhook で通知を受け取り、加盟店様 EC システムのデータと整合性を確認する処理を必ず実装してください。
利用ケース例
決済処理の途中で通信断が発生した場合
状態
加盟店様 EC システムで取引登録の結果を受け取れていない
処理
決済成功時にお送りする Webhook を受け取り、対象の取引のデータやステータスに不整合がないかを確認する
リクエスト
共通ヘッダ
| ヘッダ名 | 設定値 | 説明 |
|---|---|---|
| Content-Type | application/json |
リクエストの形式 |
| Np-User-Token | トークン値 | ユーザートークン |
Webhook は POST リクエストによる通知のため、セキュリティ上の理由からリクエストボディ（ペイロード）に認証情報であるユーザートークンを含めることを避け、HTTP ヘッダーで送信しています。
認証時ペイロード
認証完了時に user_token オブジェクトを返却します。
注意: Webhook で送信される user_token オブジェクトには、
valueフィールドが含まれません。ユーザートークンの値はNp-User-Tokenヘッダーで送信されます。完全な user_token オブジェクトの仕様については、API リファレンスをご確認ください。
{
"metadata": {
"object": "user_token",
"livemode": true
},
"merchant_user_id": "user-000001",
"service_user_id": "np_user_id_001",
"service_user_name": "090****1234",
"active": true,
"timeline": {
"issuance_timestamp": 1718208000,
"revocation_timestamp": null
}
}
決済時ペイロード
決済完了時に transaction オブジェクトを返却します。
注意: Webhook で送信される transaction オブジェクトには、
authenticationフィールドが含まれません。ユーザートークンはNp-User-Tokenヘッダーで送信されます。完全な transaction オブジェクトの仕様については、API リファレンスをご確認ください。
{
"metadata": {
"object": "transaction",
"service_transaction_id": "tr_GyhcP2Z8yh28AYS_",
"livemode": true,
"parent_transaction_ids": [],
"recurring_transaction_id": null,
"service_user_id": "np_user_id_001",
"service_user_name": "090****1234",
"options": []
},
"merchant_transaction_id": "1685354884137Zx2FB217",
"amount": 4539,
"currency": "JPY",
"description": "サンプル取引の備考",
"authorization": {
"result": 1,
"ng_reason": null
},
"timeline": {
"registration_timestamp": 1718208000,
"settlement_timestamp": null,
"reversal_timestamp": null
},
"buyer": {
"name": "山田太郎",
"phone": "0900000000",
"address": "東京都千代田区神田錦町3-7-1",
"email": "test@example.com",
"merchant_user_id": "shop-user-no-001"
},
"recipients": [],
"items": [
{
"id": "ITEM-001",
"name": "プレミアム商品A",
"category": "electronics",
"unit_price": 2500,
"quantity": 1
},
{
"id": "ITEM-002",
"name": "アクセサリーB",
"category": "accessories",
"unit_price": 2039,
"quantity": 1
}
],
"reversal": null
}
設定方法
加盟店管理システムの設定画面から Webhook の通知先 URL を設定できます。 詳しくは加盟店管理画面をご確認ください。