Create an order
POST /v1/orders creates a payment order and returns a hosted checkout_url.
Key points
- amount is a positive integer in minor units. currency is USD, HKD, or CNY; live availability depends on your account.
- out_trade_no is an optional 1–128 character merchant reference and is used for idempotency. subject is limited to 255 characters.
- notify_url must be a public HTTPS address. In live mode, omitting it requires an enabled payment.succeeded endpoint. A matching retry returns 200; changed details return 409.
- return_url is for the browser only. Add &locale=en or &locale=zh to checkout_url to set the checkout language. Do not log its bearer token.
Example
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"
}'Request fields
| Field | Required | Description |
|---|---|---|
out_trade_no | No | Merchant order reference, 1–128 characters. Generated automatically if omitted; overlong values are rejected rather than truncated. |
amount | Yes | Positive integer in the smallest currency unit. 2990 represents $29.90. Strings, decimals, and negative values are rejected. |
currency | No | USD, HKD, or CNY; defaults to USD. All three work in the sandbox. Live mode accepts only currencies enabled for your account and otherwise returns 400 invalid_request. |
subject | No | Item title, at most 255 characters. Longer titles are rejected. |
notify_url | Conditional | Public HTTPS URL for order-specific asynchronous notifications. The sandbox also rejects localhost and private addresses with 400; use a public tunnel for local testing. |
return_url | No | Buyer browser destination after successful payment. This is a user experience redirect, not a payment confirmation. |
For a live order without notify_url, at least one enabled live webhook endpoint must subscribe to payment.succeeded. An order URL overrides endpoint distribution; otherwise events follow the current endpoint configuration.
First creation returns HTTP 201. Repeating the same merchant reference with identical order details returns HTTP 200; conflicting details return HTTP 409.
Checkout language
Checkout supports Chinese and English. It follows the buyer's browser language by default, falling back to English for other languages. Append &locale=en or &locale=zh to checkout_url to choose one explicitly.
Return to your site
After payment, checkout displays a receipt and redirects to return_url after about five seconds. The buyer can return immediately or stay. Reopening an already paid link shows the receipt without redirecting.
| Placeholder | Replaced with |
|---|---|
{TRADE_NO} | KukoPay transaction number |
{OUT_TRADE_NO} | Your merchant order reference |
https://shop.example.com/orders/{OUT_TRADE_NO}/completeA browser return does not prove payment. The buyer may close the page. Fulfill only after a verified webhook or an order query.
Branding
Set the merchant name, logo, and brand color in Account → Branding and Checkout in the portal. Settings apply to sandbox and live. If unset, checkout shows the company name from onboarding.