> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Point Topup リセラー API

> Point Topup のリセラーが呼び出せる 6 つの署名付きエンドポイント：カタログ照会、購入残高照会、resellerRequestId 冪等キーによる注文作成、単一およびページ単位の注文照会、履行照会、加えて 4 つの注文ステータスと購入通知。

> [!NOTE]
>
> このページは**リセラー**向けです。リセラーとは、前払い残高に対して API 経由で Waffo Point Topup からポイントカード在庫を購入する事業者を指します。加盟店決済 API の一部ではなく、[ポイントチャージ連携の概要](/docs/ja/developer-docs/point-topup/overview) にあるサプライヤー側のモード A/B/C 連携でもありません。

メッセージ形式、金額と時刻の規約、`code` / `msg` / `data` のエンベロープ、RSA 鍵交換は Point Topup の他の部分と共通です。[Point Topup API 共通仕様](/docs/ja/developer-docs/point-topup/api-common) をご覧ください。

## どのエンドポイントを呼び出せますか？

6 つすべてが JSON ボディの `POST` です。サンドボックスと本番のベース URL はオンボーディング時に発行されます。

| エンドポイント | 用途 |
| - | - |
| `/api/v1/gamepin/products` | 貴社のカタログ：アイテム、SKU、価格、価格戦略 |
| `/api/v1/gamepin/balance` | 通貨ごとの利用可能な購入残高 |
| `/api/v1/gamepin/create` | 購入注文を発注する |
| `/api/v1/gamepin/inquiry` | 1 件の注文を読み取る（任意でカードシリアルを含む） |
| `/api/v1/gamepin/orders-inquiry` | 期間指定によるページ単位の注文一覧 |
| `/api/v1/gamepin/fulfillment-inquiry` | 即時履行注文の履行結果 |

## リセラー認証は `order/create` とどう異なりますか？

トランスポートは同じです。`X-API-KEY` と、生のボディに対する `X-SIGNATURE` を送り、オンボーディング時に交換した公開鍵で検証され、返信として検証用の署名付きレスポンスが返ります。異なる点は 3 つです。

| | 加盟店決済 API | Point Topup リセラー API |
| - | - | - |
| キーの背後にある ID | 貴社の加盟店 ID（MID） | 貴社の `resellerId` |
| ボディ内の ID | 繰り返さない | **すべての**ボディに `resellerId` を含め、キーの背後にある ID と一致させる必要がある |
| キーの範囲 | 1 つの加盟店 API セット | キーには範囲がある：購入キーは 6 つ全エンドポイントに到達でき、モード C 即時履行キーは `fulfillment-inquiry` のみに到達できる |

キーと一致しない `resellerId` はパラメーターエラーです。キーの範囲外のエンドポイントは `A0004` を返します。

## カタログを取得するにはどうすればよいですか？`priceStrategy` とは何ですか？

`products` は、貴社のリセラー契約で有効なアイテムを返します。`itemId` を渡すと 1 つのアイテムに絞り込まれ、省略するとすべてが返ります。不明または無効な `itemId` はエラーではなく空のリストを返します。

| 項目 | 意味 |
| - | - |
| `category` | `GAME_PIN` — カードシリアルが貴社に配信される。`TOP_UP` — ゲームアカウントに直接チャージされる |
| `skuList[].price` / `currency` | 単価と、注文が課金される通貨 |
| `skuList[].priceStrategy` | `FIXED_PRICE` — 表示どおりの SKU を購入する。`SPECIFIED_FACE_VALUE` — 貴社が額面を選択し、価格はそれから導出される |
| `skuList[].purchaseMaxLimit` | `SPECIFIED_FACE_VALUE` の SKU で指定できる最大額面 |

続いて `balance` は、通貨ごとに 1 エントリで現在の**利用可能**残高を返します。SKU の通貨と照合してください。注文は SKU 自体の通貨で課金されます。

## `create` には何が必要ですか？

| 項目 | 備考 |
| - | - |
| `resellerRequestId` | 貴社独自の ID、最大 32 文字。必須で、冪等キーとなる |
| `resellerId` | API キーと一致する必要がある |
| `itemId` / `skuId` | `products` から取得。不明な SKU は `A0005` を返す |
| `skuQuantity` | `1` である必要がある。それ以外は `A0006` を返す |
| `skuFaceValue` | `SPECIFIED_FACE_VALUE` の SKU で必須。SKU の額面単位の整数倍である必要がある |
| `notifyUrl` | 必須。有効な URL である必要がある。購入通知の送信先 |
| `requestedAt` | 貴社のリクエスト時刻。形式は `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`。他の形式は拒否される |
| `buyerInfo` | 任意。`TOP_UP` の SKU では、アイテムが要求するチャージ先アカウント情報を含む |
| `extendInfo` | 任意。JSON オブジェクトとしてパース可能である必要があり、最大 128 文字。そのまま返され、解釈されない |

知っておくべき動作が 2 つあります。`buyerInfo.userEmail` は常に貴社のリセラーアカウントのメールアドレスに置き換えられるため、そこに入れた顧客のアドレスは効果を持ちません。また、注文通貨の利用可能残高は注文が受理される**前**にチェックされるため、残高不足のアカウントは注文を生成せず `A0009` で即座に失敗します。

## `create` が常に `IN_PROGRESS` を返すのはなぜですか？

受理と履行が分離されているためです。`create` は `resellerRequestId`、Waffo の `orderId`、および `status` `IN_PROGRESS` を返します。引き落としと供給はその後に実行され、結果は貴社の `notifyUrl` または `inquiry` から届きます。create のレスポンスを購入結果として読まないでください。

同じ `resellerRequestId` の再送は `resellerId` + `resellerRequestId` で重複排除されます。その注文が既に完了していても、元の `orderId` が再び `IN_PROGRESS` として返されます。そのため、重複送信の後には `inquiry` を実行してください。2 つ目の注文は作成されず、再送の他の項目は無視されます。同一のリクエスト 2 件が並行して競合した場合は `A0010` を返します。少し待ってから再試行してください。

## 1 件の注文、または複数の注文を照会するにはどうすればよいですか？

`inquiry` は `orderId` **または** `resellerRequestId` を受け取ります。少なくとも 1 つが必要で、注文は貴社のものである必要があります。`returnGameCard` を `true` に設定すると `gameCardList` が返ります：シリアル、SKU が使用する場合のパスワード、`expiryType`（`FROM_PURCHASE` または `FROM_REDEMPTION`）、`expiry` です。カードは注文が `SUCCESS` になった後にのみ表示されます。

`orders-inquiry` はページ単位の形式です。`page`、`pageSize`、`startTime`、`endTime` はすべて必須で、期間は `requestedAt`（**貴社**が送信した時刻）を同じ ISO 8601 形式でフィルターし、6 か月以内に収めることが想定されています。`resellerRequestId`、`orderId`、`status` でさらに絞り込めます。`records` は `total`、`size`、`current`、`pages` で包まれ、各レコードは単一の `inquiry` と同じ形式ですが、カードシリアルは含まれません。

## 注文ステータスと金額は何を意味しますか？

| `status` | 意味 |
| - | - |
| `IN_PROGRESS` | 受理済みで、支払い中または供給中。最終ではない |
| `SUCCESS` | 供給済み。`returnGameCard` でカード詳細を取得可能 |
| `PAY_SUCCESS` | 支払い済みで、履行は貴社が完了させる — Waffo はこの SKU を配信しない |
| `FAILURE` | 支払いまたは供給が失敗。`failureCode` と `failureReason` が設定され、引き落とされた金額は貴社の残高に返還される |

`totalAmount` は購入したものの定価、`totalAmountAfterDiscount` は契約に基づいて課金される金額で、`currency` は両方に適用されます。`completedTime` は注文が最終状態になると表示されます。

`fulfillment-inquiry` は購入フローではなく即時履行（モード C）フローに属するため、形式が異なります。呼び出し元は `supplierId` として自身を識別し、注文は `salesOrderId` または `payOrderId`（少なくとも 1 つ）で識別し、応答は `fulfillmentStatus`（`IN_PROGRESS`、`SUCCESS`、`PAY_SUCCESS`、`PAY_SUCCESS_SUPPLY_FAILED`、`PAYMENT_FAILED`）であり、上記の 4 つの値ではありません。
[モード C：即時履行](/docs/ja/developer-docs/point-topup/mode-c-direct-fulfillment) をご覧ください。

## `notifyUrl` には何が届きますか？

注文が最終状態になると、Waffo は署名付きの JSON ボディを POST します。

```json theme={null}
{
  "eventType": "GAMEPIN_PURCHASE_NOTIFICATION",
  "result": { "orderId": "...", "status": "SUCCESS", "gameCardList": [ ... ] }
}
```

`result` はカードシリアルを含む完全な `inquiry` ペイロードです。Waffo の公開鍵で `X-SIGNATURE` を検証し、正確に `{"message": "success"}` で応答してください。他のボディ、または 2xx 以外のレスポンスは配信失敗としてカウントされ、再試行されます。再試行は無限に続くわけではないため、`inquiry` に対する照合ポーリングを正の情報源として維持してください。

## これらのエンドポイントはどのエラーコードを返しますか？

| コード | このフローでの意味 |
| - | - |
| `0` | 受理。引き続きビジネス `status` を確認する |
| `A0001` / `A0002` | 不明な API キー / 署名検証失敗 |
| `A0003` | パラメーター検証失敗。キーと一致しない `resellerId` を含む |
| `A0004` | このキーはこのエンドポイントを呼び出せない |
| `A0005` | アイテムまたは SKU が貴社のリセラー契約に含まれていない |
| `A0006` | `skuQuantity` が 1 以外 |
| `A0007` | 注文が存在しない、または貴社のものではない |
| `A0009` | 注文通貨のリセラー残高不足 |
| `A0010` | 同じ `resellerRequestId` に対する重複した並行リクエスト |
| `C0001` | システムエラー。再送信前に照会する |

***

一致しない点がありますか？`resellerId` と、`orderId` または `resellerRequestId` のいずれかを添えて[サポートにお問い合わせください](mailto:support@waffo.com)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.