注文を作成
POST /v1/orders は決済注文を作成し、ホスト型決済の checkout_url を返します。
重要なポイント
- amount は最小通貨単位の正の整数です。currency は USD、HKD、CNY で、本番で使える通貨はアカウント設定によります。
- out_trade_no は任意の 1～128 文字の加盟店注文番号で、冪等性にも使います。subject は最大 255 文字です。
- notify_url は公開 HTTPS が必要です。本番で省略する場合は有効な payment.succeeded エンドポイントが必要です。同内容の再試行は 200、内容の相違は 409 を返します。
- return_url はブラウザー用です。checkout_url に &locale=en または &locale=zh を追加して言語を指定できます。bearer token をログに残さないでください。
例
bash
curl -X POST "https://api.kukopay.com/v1/orders" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $KUKOPAY_API_KEY" \
-d '{
"out_trade_no": "ORD_20260921_0001",
"amount": 2990,
"currency": "USD",
"subject": "Premium plan",
"notify_url": "https://shop.example.com/webhooks/kukopay",
"return_url": "https://shop.example.com/orders/complete"
}'リクエスト項目
| 項目 | 必須 | 説明 |
|---|---|---|
out_trade_no | いいえ | 加盟店注文番号。1～128 文字。省略すると自動生成され、長すぎる値は切り詰めずに拒否されます。 |
amount | はい | 最小通貨単位の正の整数。2990 は $29.90 を表します。文字列、小数、負数は拒否されます。 |
currency | いいえ | USD、HKD、CNY。既定値は USD。テスト環境ではすべて使用可能。本番ではアカウントで有効な通貨のみ受け付け、それ以外は 400 invalid_request を返します。 |
subject | いいえ | 商品名。最大 255 文字で、超過すると拒否されます。 |
notify_url | 条件付き | 注文固有の非同期通知先となる公開 HTTPS URL。テスト環境でも localhost とプライベートアドレスは 400 になります。ローカル検証には公開トンネルを使います。 |
return_url | いいえ | 決済成功後の購入者ブラウザーの戻り先。画面上の遷移であり、決済の確証ではありません。 |
本番注文で notify_url を省略するには、payment.succeeded を購読する有効な本番 Webhook エンドポイントが必要です。注文固有の URL を指定すると端点への通常配信より優先されます。
初回作成は HTTP 201、同じ加盟店注文番号で内容も同じ再試行は HTTP 200、内容が異なる場合は HTTP 409 です。
決済画面の言語
決済画面は中国語と英語に対応します。既定では購入者のブラウザー言語に従い、それ以外は英語です。checkout_url に &locale=en または &locale=zh を追加すると固定できます。
自社サイトへの戻り先
決済後は領収表示を行い、約 5 秒後に return_url へ移動します。購入者はすぐ戻るか画面に留まることもできます。支払済みリンクを開き直しても自動転送されません。
| プレースホルダー | 置換後 |
|---|---|
{TRADE_NO} | KukoPay 取引番号 |
{OUT_TRADE_NO} | 加盟店注文番号 |
https://shop.example.com/orders/{OUT_TRADE_NO}/completeブラウザーの戻り先は支払いの証明ではありません。購入者がページを閉じる場合があります。検証済み Webhook または注文照会で確認してから提供してください。
ブランド表示
ポータルの「アカウント → ブランドと決済画面」で加盟店名、ロゴ、ブランド色を設定します。テストと本番の両方に適用され、未設定なら登録時の会社名を表示します。