ポイントチャージ API 共通仕様

本ページはモード B およびモード C の連携に適用されます。モード A は API を使用しないため対象外です。

共通インターフェース情報

項目	説明
API プロトコル	RESTful
API 形式	メッセージ本文は JSON 形式（`Content-Type: application/json`）で、UTF-8 エンコード
送信方式	HTTP `POST`
HTTPS 通信	TLS 1.2 以上
時間	特定の時点を表します。ISO 8601 規格に準拠し、精度はミリ秒単位。型 String、例 `2023-04-01T03:00:00.000Z`
通貨	ISO 4217 通貨コード標準に準拠。型 String、例 `IDR` インドネシア・ルピア、`PHP` フィリピン・ペソ、`MYR` マレーシア・リンギット
金額	法定通貨の精度は小数点以下 2 桁、単位はドル。型 String、例 `2.27`
国コード	ISO 3166-1 alpha-3 規格に準拠。型 String、例 `IDN` インドネシア、`PHL` フィリピン、`HKG` 香港

API レスポンスは、HTTP ステータスコードによってリクエスト処理の成功または失敗を示します。

区分	ステータスコード
2XX 成功	`200` OK
4XX クライアントエラー	`400` 不正なリクエスト、`401` 認証不足、`403` アクセス拒否、`404` 見つかりません、`405` メソッドが見つかりません
5XX サーバーエラー	`500` 内部サーバーエラー、`502` ゲートウェイエラー、`503` サービス利用不可、`504` ゲートウェイタイムアウト

HTTP 200 は業務上の成功を意味しません。 通信が正常に行われた（リクエストが到達し、受理され、レスポンスが返った）ことだけを示します。実際の業務結果は、さらに次の 2 点で判断してください。

レスポンス本文の code。0 のみが受理成功であり、それ以外はエラーコードに従って処理します。
data 内の業務ステータスフィールド（status、fulfillmentStatus など）。

例えば履行が失敗した注文も HTTP 200 かつ code が 0 で返却され、失敗の内容は fulfillmentStatus の PAY_SUCCESS_SUPPLY_FAILED および failureCode / failureReason に現れます。HTTP ステータスコードだけを見ると成功と誤認します。

API メッセージ構造

API リクエストおよびレスポンスメッセージは JSON 形式でフォーマットされ、UTF-8 でエンコードされます。メッセージはヘッダーとボディの 2 つの部分で構成されます。ディストリビューター（Waffo Point Topup）からサプライヤーへの API リクエスト例：

{
    "header": {
        "Content-Type": "application/json",
        "X-SIGNATURE": "..."
     },
     "body": {
         ...
     }
}

ここでの X-SIGNATURE は、Waffo Point Topup が自身の秘密鍵でボディメッセージ全体に署名した値です。サプライヤーの API レスポンス例：

{
    "header": {
        "Content-Type": "application/json",
        "X-SIGNATURE": "..."
     },
     "body": {
         "code": "xxx",
         "msg": "xxx",
         "data": {
              ...
         }
     }
}

ここでの X-SIGNATURE は、サプライヤーが自身の秘密鍵でボディメッセージ全体に署名した値です。リクエストが失敗した場合、data は空になります。

API セキュリティ

Waffo Point Topup とサプライヤー間のメッセージの非否認性を確保するために、トランザクションの署名と検証を行います。署名アルゴリズムには SHA256WithRSA を使用します。

サプライヤーのオンボーディング段階

Waffo とサプライヤーは、まず相互に RSA 公開鍵を交換します。各当事者は自身の RSA 秘密鍵を厳重に保管し、公開鍵のみを相手側と共有します。

API リクエスト段階

Waffo は自身の RSA 秘密鍵を使用してメッセージに署名し、サプライヤーに送信します。サプライヤーは Waffo の公開鍵を使用してメッセージを検証します。検証に成功した場合、サプライヤーは Waffo のリクエストを処理します。検証に失敗した場合、サプライヤーは Waffo に対して Invalid Signature（無効な署名）というエラーを返します。

API レスポンス段階

サプライヤーは自身の RSA 秘密鍵を使用してレスポンスメッセージに署名し、Waffo に返信します。Waffo はサプライヤーの公開鍵を使用してメッセージを検証します。検証に成功した場合、Waffo はサプライヤーのレスポンスを処理します。検証に失敗した場合、Waffo は調査を行い、サプライヤーに連絡します。その間、問題が解決するまで、Waffo はサプライヤーへの新規トランザクションの送信を停止します。これは、サプライヤー側でリクエストの処理が完了しているにもかかわらず、署名検証の失敗により Waffo 側でレスポンスの処理が完了していない可能性があるためです。

Waffo Point Topup とサプライヤー間の SHA256WithRSA 署名・検証フロー

エラーコード

エラーコードの接頭辞による分類：

接頭辞	分類
`A`xxxx	サプライヤー関連エラー
`B`xxxx	ユーザー関連エラー
`C`xxxx	システム関連エラー
`D`xxxx	リスク関連の拒否
`E`xxxx	不明なエラー。サプライヤー側またはサードパーティシステム内の不明なステータスにより発生します。最終的な成功／失敗ステータスを受信するまで取引を再試行する必要があります

エラーコード	説明	HTTP ステータス
`0`	Success	200
`A0001`	Invalid Api secret key	401
`A0002`	Invalid signature	401
`A0003`	Parameter validation failed	400
`A0004`	Permission denied	401
`A0005`	Purchase face value exceeds maximum value allowed	400
`A0006`	Order does not exist	400
`A0007`	Idempotent param mismatch error	400
`A0008`	Too many requests, please try again later	400
`B0001`	Buyer info does not exist	400
`B0002`	Buyer info does not match	400
`C0001`	System error	500
`C0002`	Order info mismatch error	500
`D0001`	Risk rejection	406
`E0001`	Unknown status	500

E0001（不明なステータス）を受信した場合、取引を失敗と判断しないでください。明確な成功または失敗の最終ステータスを取得するまで照会を続けてください。

RSA 鍵の生成

サプライヤーは openssl ツールを使用して RSA 鍵ペアを生成できます。

openssl のインストール

openssl.org/source から openssl をダウンロードしてインストールしてください。

鍵ペアの生成

# 秘密鍵の生成
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -out supplier_private_key.pem

# 公開鍵の生成
openssl rsa -in supplier_private_key.pem -pubout > supplier_public_key.pem

公開鍵の交換

supplier_public_key.pem を Waffo に渡し、Waffo 側の公開鍵を受け取ってください。

秘密鍵は安全に保管し、絶対に第三者に開示しないでください。

次のステップ

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

リアルタイム取得のリクエスト・レスポンス項目と冪等性の要件。

モード C：即時履行 API

URL 署名リダイレクト、即時履行、即時履行結果照会。

はじめに

コアコンセプト

インテグレーション

Webhook

SDK

ツールとリファレンス