モード B：ポイントコード取得 API

モード B は、API 機能を備えたポイント在庫システムを有するサプライヤー向けです。ユーザーが支払いを完了した後、Waffo Point Topup がサプライヤーの API を呼び出してリアルタイムでポイントコードを取得します。

メリット

リアルタイムポイントコード取得
手動在庫管理不要
自動在庫同期

ユースケース

デジタルポイント生成システムを有するゲームパブリッシャー
既存 API を有するポイントコードディストリビューター

連携フロー

モード B のポイントコード取得フロー：決済完了後に Waffo がサプライヤーのエンドポイントを呼び出してコードを取得し、ユーザーにメール送信

API 一覧

No.	API 名	説明	提供元	連携要否
1	ポイントコード取得	リアルタイムポイントコード取得	サプライヤー	任意連携（サンプル仕様）

本ページの API 仕様はサンプル／参考用のみです。すでにポイントコード取得用の API を有する場合、既存の API ドキュメントを Waffo Point Topup に提供すれば統合が可能です。Waffo Point Topup はサプライヤーの既存 API インターフェースに対応するため、本ページに合わせて作り直す必要はありません。

ユーザーリダイレクト

自社ウェブサイトから Waffo Point Topup へユーザーをリダイレクトしたい場合、モード C の URL 署名方式を利用できます。あるいは、署名なしで直接リンクを提供するだけでも構いません。

https://{supplier}.waffoplay.com/{site_code}/

ポイントコード取得エンドポイント

ユーザーが支払いを完了した後、Waffo Point Topup によって呼び出され、サプライヤーからポイントコードを取得します。

項目	値
Method	`POST`
Path	サプライヤーが定義
認証	共通 API 署名（SHA256WithRSA）。API 共通仕様を参照

冪等性の要件： サプライヤーは distributorOrderId + distributorId を使用して冪等性をサポートする必要があります。同じリクエストが複数回受信された場合、在庫を再度減算せずに同じポイントコードを返してください。

リクエスト

フィールド名	説明	型	必須
`distributorId`	サプライヤーが Waffo Point Topup に割り当てたディストリビューター ID	String(64)	必須
`distributorOrderId`	Waffo Point Topup の注文 ID。`distributorId` と併せて冪等キーとして使用	String(64)	必須
`skuId`	SKU 識別子	String(128)	必須
`quantity`	取得するポイント数（通常は 1）	Integer	必須
`faceValue`	額面金額（動的価値の商品向け）	String(32)	任意
`requestedAt`	Waffo Point Topup 側リクエスト時間	String(32)	必須

レスポンス

フィールド名		説明	型	必須
`distributorOrderId`		Waffo Point Topup の注文 ID	String(64)	必須
`status`		注文ステータス：`SUCCESS` ポイント取得成功、`FAILURE` 取得失敗	String(24)	必須
`pointList`		ポイントコードのリスト。`status` が `SUCCESS` の場合のみ返却	Array	任意
	`pointCode`	ポイントコード	String(128)	必須
	`expiryDate`	有効期限	String(32)	任意
	`faceValue`	額面金額	String(32)	任意
`failureCode`		失敗コード（`status` が `FAILURE` の場合）	String(24)	任意
`failureReason`		失敗理由	String(128)	任意

サンプル

{
  "distributorId": "WAFFO_POINT_TOPUP_001",
  "distributorOrderId": "WP202501050001",
  "skuId": "SUPPLIER_POINT_001",
  "quantity": 1,
  "faceValue": "1000",
  "requestedAt": "2025-01-05T10:30:00.000Z"
}

{
  "code": "0",
  "msg": "success",
  "data": {
    "distributorOrderId": "WP202501050001",
    "status": "SUCCESS",
    "pointList": [
      {
        "pointCode": "ABCD-1234-EFGH-5678",
        "expiryDate": "2026-12-31",
        "faceValue": "1000"
      }
    ]
  }
}

{
  "code": "0",
  "msg": "success",
  "data": {
    "distributorOrderId": "WP202501050001",
    "status": "FAILURE",
    "failureCode": "INSUFFICIENT_INVENTORY",
    "failureReason": "No available points in inventory"
  }
}

status が FAILURE の場合は業務上の失敗であり、HTTP ステータスコードと外側の code は成功を返します。システムレベルのエラーはエラーコードに従って返してください。

次のステップ

API 共通仕様

メッセージ構造、RSA 署名と検証、エラーコード、鍵の生成。

モード C：即時履行 API

ポイントコードを発行せずユーザーアカウントを直接チャージする場合は、モード C を参照してください。

はじめに

コアコンセプト

インテグレーション

Webhook

SDK

ツールとリファレンス

ポイントチャージ API

モード B：ポイントコード取得 API

メリット

ユースケース

連携フロー

API 一覧

ユーザーリダイレクト

ポイントコード取得エンドポイント

リクエスト

レスポンス

サンプル

次のステップ

API 共通仕様

モード C：即時履行 API

メリット

ユースケース

​連携フロー

​API 一覧

​ユーザーリダイレクト

​ポイントコード取得エンドポイント

​リクエスト

​レスポンス

​サンプル

​次のステップ

API 共通仕様

モード C：即時履行 API

連携フロー

API 一覧

ユーザーリダイレクト

ポイントコード取得エンドポイント

リクエスト

レスポンス

サンプル

次のステップ