# KukoPay

> KukoPay is a payment gateway for businesses selling across borders: one server-side API for hosted checkout, orders, refunds, webhooks, wallets and payouts.

The full documentation is written in Chinese at https://kukopay.com/docs; English, Japanese, Korean and German summaries of every page live under /en/docs, /ja/docs, /ko/docs and /de/docs.

## Public entry points

- Website: https://kukopay.com/
- Developer documentation: https://kukopay.com/docs
- Merchant portal: https://web.kukopay.com
- Merchant API base URL: https://api.kukopay.com/v1
- OpenAPI 3.1 contract (generated from the server code): https://api.kukopay.com/v1/openapi.json
- Epay-compatible gateway: https://api.kukopay.com/epay

## Documentation

### Get started

- [Documentation home](https://kukopay.com/docs): Integrate KukoPay's server-side HTTP + JSON API, redirect customers to hosted checkout, and confirm the final result with a signed webhook.
- [Quickstart](https://kukopay.com/docs/quickstart): Create a sandbox order, open hosted checkout, then verify the signed payment event before fulfilling it.
- [Merchant onboarding](https://kukopay.com/docs/onboarding): What businesses and individuals need to submit for review, and how approval unlocks live API keys, payment limits, currencies and payment methods.
- [Teams and roles](https://kukopay.com/docs/team): Invite colleagues to your merchant account with only the access they need: what owners, admins, developers and viewers can do, and how ownership moves.
- [Authentication and environments](https://kukopay.com/docs/authentication): Authenticate every merchant API request with X-Api-Key; the kuko_test_ or kuko_live_ prefix selects the environment. Also covers IP allowlists and rate limits.
- [Payment flow](https://kukopay.com/docs/payment-flow): An order moves from creation through checkout to payment, refund, or expiry, with each balance change recorded in the ledger.

### Plugins and integrations

- [Choose an integration](https://kukopay.com/docs/integrations): Every integration runs on the same server API, hosted checkout and signed webhooks; choose by who writes the code.
- [Xboard plugin](https://kukopay.com/docs/integrations/xboard): Upload the KukoPay plugin in the Xboard admin, enter an API key and webhook signing secret, and accept payments through hosted checkout.
- [Epay-compatible gateway](https://kukopay.com/docs/integrations/epay): Systems that already speak the epay (易支付) protocol can take payments through KukoPay by entering a gateway address, merchant ID and key — no plugin needed.

### Integration guides

- [Webhooks](https://kukopay.com/docs/webhooks): KukoPay sends signed events for payments, refunds and disputes: event types, HMAC-SHA256 signature checks, secret rotation, retries and missed events.
- [Idempotency and retries](https://kukopay.com/docs/idempotency): Two idempotency layers let you retry after timeouts without creating duplicate payments, refunds, or side effects.
- [Sandbox testing](https://kukopay.com/docs/testing): Use sandbox keys to test the full payment lifecycle without real money: the scenarios worth covering, test card numbers, and simulated wallets and 3D Secure.

### Funds

- [Fees and settlement](https://kukopay.com/docs/settlement): How payment fees are calculated, when a successful payment reaches your wallet, and what the available, withdrawable and frozen balance figures mean.
- [Chargebacks and disputes](https://kukopay.com/docs/disputes): A chargeback freezes the disputed amount while the issuer reviews evidence. Respond before the deadline to avoid an automatic loss.
- [Payouts](https://kukopay.com/docs/payouts): Withdraw wallet funds to a reviewed settlement account: the $100 / HK$100 minimum and $5 fee per payout, the review and transfer states, and when money arrives.

### API reference

- [Create an order](https://kukopay.com/docs/api/orders): POST /v1/orders creates a payment order and returns a hosted checkout_url. Covers every request field, order expiry, checkout language and the return URL.
- [Retrieve an order](https://kukopay.com/docs/api/orders-query): GET /v1/orders/{trade_no} retrieves an order by KukoPay transaction number; you can also look it up with the merchant reference.
- [Expire an order](https://kukopay.com/docs/api/orders-expire): POST /v1/orders/{trade_no}/expire closes a pending order so its checkout link can no longer accept payment.
- [Receipts](https://kukopay.com/docs/api/receipts): Every paid order has a numbered, printable receipt that can be emailed to the buyer automatically or sent by you later.
- [Create a refund](https://kukopay.com/docs/api/refunds): POST /v1/refunds starts a full or partial refund for a paid order; GET /v1/refunds/{refund_no} retrieves its status.
- [Disputes](https://kukopay.com/docs/api/disputes): List and retrieve chargebacks and the funds they hold, assemble and submit evidence over several requests, or accept a dispute you cannot win.
- [Payment links](https://kukopay.com/docs/api/payment-links): A payment link is a stable URL that creates a new order on each visit, useful when you do not want to build a checkout integration.
- [Retrieve balance](https://kukopay.com/docs/api/balance): GET /v1/balance?currency=USD returns the wallet for the environment your API key selects: available, withdrawable and frozen balances, plus lifetime totals.
- [Balance transactions](https://kukopay.com/docs/api/balance-transactions): Balance transactions record every wallet movement and are the recommended source for daily reconciliation.
- [Events](https://kukopay.com/docs/api/events): Every change on your account is recorded as an event. The Events API lets you read them again, so a missed or failed webhook delivery can be recovered.
- [Webhook endpoints](https://kukopay.com/docs/api/webhook-endpoints): Create multiple webhook destinations, subscribe them to event types, and rotate their signing secrets safely.
- [API request logs](https://kukopay.com/docs/api/logs): Request logs show the request and response of each of your own API calls, with secrets redacted, so you can diagnose failures. They are kept for 30 days.

### API conventions

- [Lists, pagination, and export](https://kukopay.com/docs/api/pagination): List APIs use cursor pagination and share filters for page size and creation time; some support CSV export.
- [Metadata](https://kukopay.com/docs/api/metadata): Attach your own business identifiers to orders, refunds and payment links with metadata, query orders by it, and merge or delete single keys later.
- [Errors](https://kukopay.com/docs/api/errors): API errors include an HTTP-aligned code, stable machine-readable error, human message, optional param, doc_url, and request_id.

## Blog

Traditional Chinese translations are under https://kukopay.com/zh/blog.

- [How to accept Apple Pay and Google Pay on your website without building a checkout](https://kukopay.com/blog/apple-pay-google-pay): How to accept Apple Pay and Google Pay on your website through a hosted checkout: no domain files or code, what they cost, how to enable them and test.
- [How to cancel unpaid orders automatically without losing late payments](https://kukopay.com/blog/cancel-unpaid-orders): How to cancel unpaid orders automatically: set a payment expiration time, close the checkout first, and handle a buyer who pays after cancellation.
- [How to secure your merchant account: two-step sign-in, sign-in alerts and protected payouts](https://kukopay.com/blog/merchant-account-security): How to secure a merchant account against takeover: turn on two-step sign-in, watch sign-in alerts, sign out everywhere, and how payouts are protected.
- [Multilingual checkout: how to show buyers the checkout, receipt and emails in their own language](https://kukopay.com/blog/multilingual-checkout): How a multilingual checkout works: choose the checkout language per buyer, keep the receipt and email in the same language, and localise more than words.
- [How to accept payments on multiple websites with one merchant account](https://kukopay.com/blog/multiple-websites): How to accept payments on multiple websites or stores with one merchant account: what each site gets of its own, what stays shared, and how to set it up.
- [Payment API error handling: error codes, error types, and which errors are safe to retry](https://kukopay.com/blog/payment-api-errors): How to handle payment API errors: read the error envelope, branch on codes not messages, know which errors are safe to retry, and debug with request_id.
- [Payment metadata: how to attach your own IDs to orders, refunds and payment links](https://kukopay.com/blog/payment-metadata): How to use payment metadata to link payments to your own records: what to store, the limits, finding orders by metadata, and updating it safely.
- [Payment status explained: what pending, paid, failed, expired and refunded mean](https://kukopay.com/blog/payment-status): Payment status explained: what pending, paid, failed, expired, partially refunded and refunded mean, how orders move between them, and what to do at each.
- [Sandbox vs live mode: how payment test mode works and how to go live safely](https://kukopay.com/blog/sandbox-vs-live): Sandbox vs live mode for a payment API: what is separate, what behaves differently in test mode, and a go-live checklist for switching to live keys safely.
- [Payment dashboard user roles: who on your team should refund, pay out and manage API keys](https://kukopay.com/blog/team-roles): How payment dashboard user roles work: owner, admin, developer and viewer permissions, inviting your team safely, and who should be able to move money.
- [Webhook endpoints: how to set up multiple endpoints, subscribe to events and rotate secrets](https://kukopay.com/blog/webhook-endpoints): How to set up webhook endpoints for payments: multiple endpoints, event subscriptions, storing and rotating the signing secret, and pausing safely.
- [Webhooks vs polling: how to get payment results reliably](https://kukopay.com/blog/webhooks-vs-polling): Webhooks vs polling for payment status: why webhooks should drive fulfilment, where a lookup belongs, and how to back both up so no payment is missed.
- [What is 3D Secure? How 3DS authentication works and what it means for merchants](https://kukopay.com/blog/3d-secure): What 3D Secure is, how 3DS authentication works, frictionless vs challenge flows, why a 3D Secure check fails, and how to test it before going live.
- [API key rotation: how to rotate payment API keys without downtime, and what to do if one leaks](https://kukopay.com/blog/api-key-rotation): How API key rotation works for a payment API: rotate without downtime, revoke a leaked key at once, confirm an old key is unused, and keep keys safe.
- [API rate limits and 429 Too Many Requests: how payment APIs throttle, and how to handle it](https://kukopay.com/blog/api-rate-limits): What API rate limits are, why a payment API returns 429 Too Many Requests, how to honour Retry-After, and how to design calls that stay under the limit.
- [Card decline codes explained: what “do not honor” means and what to do next](https://kukopay.com/blog/card-decline-codes): Card decline codes explained: what do not honor, insufficient funds and incorrect CVC mean, soft vs hard declines, and how to recover the sale.
- [What is a hosted payment page? Hosted vs integrated checkout, PCI scope and branding](https://kukopay.com/blog/hosted-payment-page): What a hosted payment page is, how it compares with an integrated checkout, what it means for PCI scope, and how to brand it and bring buyers back.
- [What is an idempotency key? How to retry payment API requests without charging twice](https://kukopay.com/blog/idempotency-key): What an idempotency key is, why payment APIs need one, how the Idempotency-Key header replays a response, and how to retry without double-charging.
- [What is KYB verification? The documents you need to accept payments as a business](https://kukopay.com/blog/kyb-verification): What KYB verification is, how it differs from KYC, the documents a payment provider asks for, how review works, and how to pass KYB the first time.
- [Partial refunds explained: how to issue one, how long refunds take, and whether fees come back](https://kukopay.com/blog/partial-refunds): How partial refunds work for online payments: issuing one, how long a refund takes, why processing fees are not refunded, refund deadlines and disputes.
- [What is a payment link? How to create one and get paid without building a checkout](https://kukopay.com/blog/payment-links): What a payment link is, how to create a payment link in the dashboard or API, where to share it, how to cap it, and when to use the checkout API.
- [Payment receipts for online payments: what to include, how to send one, and receipt vs invoice](https://kukopay.com/blog/payment-receipt): What a payment receipt is, what it should include, how to send one automatically after payment, and how it differs from an invoice or tax invoice.
- [Payment reconciliation: how to match orders, fees, refunds and payouts to your bank account](https://kukopay.com/blog/payment-reconciliation): A practical guide to payment reconciliation: match orders to payments, explain your balance with the ledger, tie payouts to bank deposits, and fix gaps.
- [What is payment settlement? How money gets from a successful payment to your bank account](https://kukopay.com/blog/payment-settlement): What payment settlement is, how long it takes, available vs withdrawable balance, how payouts reach your bank, and what can hold money back along the way.
- [Test credit card numbers for payment testing: every outcome, and what to test besides cards](https://kukopay.com/blog/test-credit-card-numbers): Test credit card numbers for success, declines and 3D Secure, how to use them in a sandbox, and the webhook, refund and wallet tests that matter too.
- [Payment webhook not received? A checklist to find the cause and recover missed events](https://kukopay.com/blog/webhook-not-received): Payment webhook not received? Check the delivery history, the URL, timeouts, signatures and subscriptions, then recover missed events from the events API.
- [How to accept Alipay and WeChat Pay online: a guide for international merchants](https://kukopay.com/blog/accept-alipay-wechat-pay): How to accept Alipay and WeChat Pay online as a merchant outside China: how buyers pay, enabling both wallets, fees, refund deadlines and sandbox tests.
- [How to accept international payments on your website: currencies, payment methods and fees](https://kukopay.com/blog/accept-international-payments): How to accept international payments on your website: a multi-currency checkout, cards and wallets, what it costs, payouts and a go-live checklist.
- [What is a chargeback? Chargeback rate thresholds, evidence and what happens to the money](https://kukopay.com/blog/chargeback-guide): How a chargeback freezes the disputed amount, why a balance can go negative, the 0.65% and 0.9% chargeback-rate thresholds, and the evidence to submit.
- [How cross-border payment fees are calculated: the formula, small orders and payout costs](https://kukopay.com/blog/cross-border-payment-fees): A worked example of percentage-plus-fixed-fee pricing: the fixed fee in USD, HKD and CNY, why small orders cost more, and what refunds and payouts add.
- [Integrating the epay (易支付) protocol: MD5 signatures, notifications and three common pitfalls](https://kukopay.com/blog/epay-integration-guide): How epay's submit.php, mapi.php and api.php fit together, how to compute the MD5 signature, set the order timeout and debug missing notifications.
- [Can you accept international payments without a registered business? Rules, limits and payouts for individuals](https://kukopay.com/blog/individual-cross-border-payments): Individuals aged 18 or over can accept payments with KukoPay using their own ID: what to prepare, excluded categories, payment limits and payout rules.
- [Duplicate payment webhooks: verify signatures and stay idempotent so you only fulfil once](https://kukopay.com/blog/payment-webhook-idempotency): Payment webhooks are retried, so one payment can reach you twice. Fulfil it exactly once with HMAC-SHA256 checks, a unique event ID and a transaction.
- [return_url vs notify_url: why a payment redirect is not proof of payment](https://kukopay.com/blog/return-url-vs-notify-url): A buyer landing back on your site does not mean the money arrived. How return_url differs from notify_url, and the right way to decide an order is paid.

## Key facts

- Payment methods: cards, Apple Pay, Google Pay, Alipay, WeChat Pay and PayPal; live methods are enabled per merchant at approval.
- Currencies: USD, HKD, CNY. Each currency is a separate wallet; there is no automatic conversion.
- Standard pricing: 3.5% plus a fixed fee per successful payment ($0.30 · HK$2.35 · ¥2.00); signed merchants have their own rates.
- Amounts are integers in the currency's minor unit: 2990 means $29.90.
- `kuko_test_` keys select the sandbox and `kuko_live_` keys select live mode; there is no environment field in requests.
- Fulfil only after a verified `payment.succeeded` webhook (HMAC-SHA256, possibly several `v1=` signatures during secret rotation) or an order query, never on a browser redirect.
- `out_trade_no`, `out_refund_no`, the `Idempotency-Key` header and the webhook event `id` are the idempotency boundaries.
- Every response carries a `request_id`; support asks for it.