Skip to contentFree sandbox — run your first test order in minutes

Blog

Payments,explained down to the detail.

The pitfalls we hit building a payment stack, the trade-offs we made and the practices we verified. Every post leads to docs you can follow straight away.

RSS feed
  1. Hand-drawn illustration of a phone app opening a checkout in a browser sheet and returning through an https link, with a server confirming the payment, next to a person walking towards it

    Accept payments in a mobile app: hosted checkout, return links and confirming the result

    How to accept payments in a mobile app: create the order on your server, open the hosted checkout, return with a universal link, and confirm on the webhook.

  2. Hand-drawn illustration of two PHP files, checkout.php and webhook.php, linked to a hosted checkout and back, next to a person with folded arms

    PHP payment integration: accept payments with cURL and a verified webhook

    A PHP payment gateway integration step by step: create an order with cURL, redirect to checkout, verify the webhook with hash_equals and fulfil once.

  3. Hand-drawn illustration of a Python file with a create_order function and a webhook view, linked to a hosted checkout and back, next to a person pointing at it

    Python payment integration: accept payments in Flask or Django, with webhooks

    A Python payment integration step by step: create an order with requests, redirect to checkout, verify the webhook in Flask or Django, and fulfil once.

  4. Hand-drawn illustration of a website mock-up with ticked sections for products and prices, contact, terms and refund policy, beside a review stamp, next to a person with hands in their pockets

    Website requirements for payment gateway approval: a checklist before you apply

    Website requirements for payment gateway approval: what reviewers check, the pages a site needs, and the mistakes that get an application sent back.

  5. Hand-drawn illustration of a browser window with a crossed-out kuko_live_ key and an arrow to a server holding the key that calls the API, next to a person pointing at it

    API key in frontend code: why a payment API key must stay on your server

    Is it safe to put an API key in frontend JavaScript? Why a payment API key stays on your server, how browsers pay without one, and what to do after a leak.

  6. Hand-drawn illustration of a checkout leading through a webhook to a download, a course and a licence key, next to a person sitting on a box

    Payment gateway for digital products: how to sell downloads, courses and software internationally

    How to take payments for digital products internationally: who may sell them, delivering on the webhook, receipts, refunds, chargeback evidence and tax.

  7. Hand-drawn illustration of an Express server with two routes, POST /checkout and POST /webhooks, linked to a hosted checkout and back, next to a person with hands in their pockets

    Node.js payment integration: accept payments in an Express app, from order to webhook

    A Node.js payment integration with Express, step by step: create an order, redirect to checkout, verify the webhook signature, fulfil once and test it.

  8. Hand-drawn illustration of an order card labelled out_trade_no and trade_no linked to two payment_id cards, one crossed out, next to a person with folded arms

    Transaction ID vs order ID: which payment identifier to store, and which to match on

    Transaction ID vs order ID explained: what each payment identifier means, which one to store, which to reconcile on, and which to give support.

  9. Hand-drawn illustration of a $29.90 price tag turned into the integer 2990 by an arrow, beside a crossed-out 29.9 float, next to a person pointing at it

    Why payment APIs take the amount in cents: minor units, integers and rounding

    Why payment APIs take the amount in cents: what minor units are, why floats break money, how to convert prices safely, and the rules KukoPay applies.

  10. Hand-drawn illustration of a checkout with toggles for card, Apple Pay, Google Pay, Alipay, WeChat Pay and PayPal, some switched on and one off, next to a person walking towards it

    Checkout payment methods: which ones to offer, and how to choose what buyers see

    How to choose checkout payment methods: which to offer for each market, how to request more, how to hide some from the checkout, and how each is priced.

  11. Hand-drawn illustration of a payout button behind a pause sign, with payments still flowing into a wallet, next to a person with folded arms

    Payouts suspended: why a payment provider pauses your payouts, and how to get them back

    Why payouts get suspended — chargeback rate, an expired ID, a frozen account, a negative balance — what still works meanwhile, and how payouts are restored.

  12. Hand-drawn illustration of three webhook envelopes numbered 1, 2 and 3 arriving in the order 2, 3, 1 at a server that re-reads the order before acting, next to a person with hands in their pockets

    Webhooks out of order: how to handle events that arrive in the wrong sequence

    Why webhooks can arrive out of order, what goes wrong if you apply them as they come, and four ways to handle event ordering safely in a payment integration.

  13. Hand-drawn illustration of an openapi.json file feeding a generator that outputs TypeScript, Python and a Postman collection, next to a person with hands in their pockets

    Generate a payment API client from an OpenAPI spec: types, SDKs, Postman and contract tests

    How to generate a payment API client from an OpenAPI spec: TypeScript types, SDKs with OpenAPI Generator, Postman import and contract tests.

  14. Hand-drawn illustration of a browser showing a payment success page with a tick, an order number and a receipt link, with a dotted line back to an order status check, next to a person pointing at it

    Payment success page: what to show after checkout, and how to know the payment really succeeded

    How to build a payment success page: what to show buyers after checkout, how to check the order before saying paid, and how to handle a pending payment.

  15. Hand-drawn illustration of a bank account form with holder, account number and SWIFT fields under review, an arrow to a bank building, next to a person sitting on a box

    Payout bank account: how to add a settlement account, and why it must match your business

    How to add a payout bank account: the details you need, why the holder must match your verified business, how review works, and why changing it is checked.

  16. Hand-drawn illustration of a V2Board settings form with gateway, pid and key fields pointing to a checkout and back with a success reply, next to a person with folded arms

    V2Board payment gateway: accept card and wallet payments through the built-in EPay

    How to set up a V2Board payment gateway with the built-in EPay method: gateway URL, merchant ID and key, the order timeout to choose, testing and fixes.

  17. Hand-drawn illustration of a $49.00 price tag, a card and a phone wallet, and a USD wallet, next to a person sitting on a box

    How to accept USD payments online from overseas customers

    How to accept USD payments online from overseas customers: pricing in US dollars, payment methods, fees, the USD balance and payouts, and limits.

  18. Hand-drawn illustration of a list of orders split into pages, with a cursor arrow pointing from the last row of one page to the next, next to a person pointing at it

    Cursor-based pagination explained: how to page through payment API lists without missing records

    Cursor-based pagination explained: limit, starting_after, ending_before and has_more, why offset pagination skips records, and how to fetch every page.

  19. Hand-drawn illustration of two servers sending requests to an API gate, one IP address allowed with a tick and one refused with 403 ip_not_allowed, next to a person with hands in their pockets

    API IP whitelisting: how to restrict payment API keys to your own servers

    How API IP whitelisting works for a payment API: finding your egress IP, IPv4, CIDR and IPv6 entries, ip_not_allowed errors, and when not to use it.

  20. Hand-drawn illustration of three boxes labelled gateway, merchant account and aggregator connected by arrows from a checkout to a bank, next to a person walking towards them

    Merchant account vs payment gateway vs payment aggregator: what's the difference?

    Merchant account vs payment gateway vs payment aggregator explained: what each one does, who holds the money, and which a small cross-border seller needs.

  21. Hand-drawn illustration of a wallet showing −$44.90 with a chargeback card pulling money out and new payments flowing back in, next to a person with folded arms

    Negative balance on a merchant account: why it happens and how it is made good

    Why a merchant account balance can go negative after a chargeback, what a negative balance blocks, how it is made good, and how to avoid one.

  22. Hand-drawn illustration of a checklist of business categories, some ticked and some crossed out, beside a review stamp, next to a person with folded arms

    Prohibited businesses: what you cannot sell through a payment provider, and why

    Which businesses payment providers prohibit — gambling, crypto, adult content, drugs, weapons and more — why the lists exist, and how they are enforced.

  23. Hand-drawn illustration of a webhook travelling from the cloud through a tunnel to a laptop showing localhost:3000, next to a person pointing at it

    How to test webhooks locally: receive payment webhooks on localhost with a tunnel

    How to test webhooks locally: why localhost cannot receive them, how to expose it with a tunnel, and how to send test events, simulate payments and replay.

  24. Hand-drawn illustration of an Xboard plugin box with fields for an API key and a signing secret, connected to a checkout and back with a signed notification, next to a person walking towards it

    Xboard payment plugin: how to accept card and wallet payments in Xboard

    How to set up the Xboard payment plugin: install it, add the API key and signing secret, set currency and rate, test in the sandbox, and fix common issues.

  25. Hand-drawn illustration of an HK$380.00 price tag, a card and a phone wallet, and an HKD wallet, next to a person with hands in their pockets

    How to accept HKD payments online: selling to Hong Kong in Hong Kong dollars

    How to accept HKD (Hong Kong dollar) payments online: pricing in HKD, the payment methods on offer, fees, the HKD balance and payouts, and limits.

  26. Hand-drawn illustration of two identical $29.90 charges, one of them returning to the card along an arrow, next to a person with folded arms

    Duplicate payments: what to do when a customer says they were charged twice

    What to do about duplicate payments when a customer says they were charged twice: find out what happened, refund the right one, and prevent it.

  27. Hand-drawn illustration of a refund policy page with a 14-day window, a partial refund bar and a returning arrow to a card, next to a person with folded arms

    Refund policy for an online store: what to include, and how it holds up in a dispute

    How to write a refund policy for an online store: the window, partial refunds, fees, wallet deadlines, where to show it, and its role in a dispute.

  28. Hand-drawn illustration of a webhook request with a t= and v1= signature header passing through an HMAC-SHA256 check to a tick, next to a person pointing at it

    How to verify webhook signatures (HMAC-SHA256): a step-by-step guide with code

    How to verify a webhook signature with HMAC-SHA256: the raw body, the timestamp, constant-time comparison, secret rotation, and why verification fails.

  29. Hand-drawn illustration of a ¥268.00 price tag next to Alipay, WeChat Pay and UnionPay labels and a CNY wallet, next to a person walking towards them

    How to accept RMB (CNY) payments online from customers in China

    How to accept RMB (CNY) payments online from customers in China: CNY pricing, Alipay, WeChat Pay and UnionPay, costs, and how CNY is paid out.

  30. Hand-drawn illustration of a card statement line with a question mark, a receipt bearing the shop's name and a reply arrow, next to a puzzled person with folded arms

    Friendly fraud and unrecognized charges: how to stop customers disputing payments they made

    What friendly fraud is, why buyers dispute charges they made, and how a known name, receipts, quick refunds and evidence prevent these chargebacks.

  31. Hand-drawn illustration of four paths labelled plugin, epay, link and API leading from a website to one checkout, next to a person pointing at them

    Payment gateway integration: 4 ways to connect your website, from no-code to full API

    Payment gateway integration options compared: plugins, epay gateways, payment links and the API — what each needs, what it does, and how to choose.

  32. Hand-drawn illustration of three gauges labelled per payment, 24h and 30d with needles near their limits, and a 400 payment_limit_exceeded card, next to a person with folded arms

    Payment limits explained: per-payment, 24-hour and 30-day caps, and what “payment limit exceeded” means

    How merchant payment limits work: per-payment and rolling 24-hour and 30-day caps, what counts, what payment_limit_exceeded means, and how to raise them.

  33. Hand-drawn illustration of a phone with a fingerprint check beside a checkout with two one-tap wallet buttons above the card fields, next to a person pointing at it

    How to accept Apple Pay and Google Pay on your website without building a checkout

    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.

  34. Hand-drawn illustration of an order card with an hourglass, a 30-minute timer and a closed padlock over a checkout page, next to a person with hands in pockets

    How to cancel unpaid orders automatically without losing late payments

    How to cancel unpaid orders automatically: set a payment expiration time, close the checkout first, and handle a buyer who pays after cancellation.

  35. Hand-drawn illustration of a phone showing a six-digit code next to a shield over a bank building, with an envelope alert, next to a person pointing at it

    How to secure your merchant account: two-step sign-in, sign-in alerts and protected payouts

    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.

  36. Hand-drawn illustration of one checkout page with language tabs en, zh, ja, ko and de and a receipt behind it, next to a person walking towards it

    Multilingual checkout: how to show buyers the checkout, receipt and emails in their own language

    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.

  37. Hand-drawn illustration of three website windows labelled web, ios and brand2, each with its own key, connected to one shared wallet, next to a person walking towards them

    How to accept payments on multiple websites with one merchant account

    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.

  38. Hand-drawn illustration of an error response card showing code 400, error and param fields, sorted into retry and fix-first trays, next to a person pointing at it

    Payment API error handling: error codes, error types, and which errors are safe to retry

    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.

  39. Hand-drawn illustration of an order card with a luggage tag listing customer_id, source and campaign, connected to a database cylinder, next to a person with folded arms

    Payment metadata: how to attach your own IDs to orders, refunds and payment links

    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.

  40. Hand-drawn illustration of a status flow from pending to paid, failed and expired, then partially refunded and refunded, next to a person walking towards it

    Payment status explained: what pending, paid, failed, expired and refunded mean

    Payment status explained: what pending, paid, failed, expired, partially refunded and refunded mean, how orders move between them, and what to do at each.

  41. Hand-drawn illustration of a toggle switch between kuko_test_ and kuko_live_ keys, a sandbox bucket and a coin, and a rocket ready for launch, next to a person pointing at it

    Sandbox vs live mode: how payment test mode works and how to go live safely

    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.

  42. Hand-drawn illustration of a permission grid with owner, admin, developer and viewer rows ticked against refund, payout and keys, next to a person with folded arms

    Payment dashboard user roles: who on your team should refund, pay out and manage API keys

    How payment dashboard user roles work: owner, admin, developer and viewer permissions, inviting your team safely, and who should be able to move money.

  43. Hand-drawn illustration of one event source fanning out to three endpoint boxes with event checklists, and a key with a 24h dual-signing label, next to a person walking towards them

    Webhook endpoints: how to set up multiple endpoints, subscribe to events and rotate secrets

    How to set up webhook endpoints for payments: multiple endpoints, event subscriptions, storing and rotating the signing secret, and pausing safely.

  44. Hand-drawn illustration contrasting a server pushing one envelope to a shop with a loop of repeated "anything new?" arrows, next to a person with folded arms

    Webhooks vs polling: how to get payment results reliably

    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.

  45. Hand-drawn illustration of a phone showing a shield with a check mark and a six-digit code, a bank card with an arrow to the phone, and a person pointing at it

    What is 3D Secure? How 3DS authentication works and what it means for merchants

    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.

  46. Hand-drawn illustration of two keys on a ring with a circular arrow between them, an old key fading on a 24h timer and a new key marked live, next to a person with folded arms

    API key rotation: how to rotate payment API keys without downtime, and what to do if one leaks

    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.

  47. Hand-drawn illustration of a funnel with request arrows piling up above it, a 429 sign and an hourglass labelled Retry-After, next to a person pointing at it

    API rate limits and 429 Too Many Requests: how payment APIs throttle, and how to handle it

    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.

  48. Hand-drawn illustration of a bank card marked with a cross, with do_not_honor, insufficient_funds and expired_card tags around it and a puzzled person with folded arms

    Card decline codes explained: what “do not honor” means and what to do next

    Card decline codes explained: what do not honor, insufficient funds and incorrect CVC mean, soft vs hard declines, and how to recover the sale.

  49. Hand-drawn illustration of a shop page with an arrow redirecting to a separate checkout page with a padlock, a logo and brand colour swatches, next to a person pointing at it

    What is a hosted payment page? Hosted vs integrated checkout, PCI scope and branding

    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.

  50. Hand-drawn illustration of three identical request cards carrying the same Idempotency-Key going into one server box that returns a single 201 response, a key, and a person with folded arms

    What is an idempotency key? How to retry payment API requests without charging twice

    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.

  51. Hand-drawn illustration of a company document with a stamp, an ID card and a magnifying glass over a checklist, with an approved status pill, and a person walking towards them

    What is KYB verification? The documents you need to accept payments as a business

    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.

  52. Hand-drawn illustration of a receipt for 48.00 with 20.00 torn off and an arrow carrying it back to a wallet, next to a person standing with hands in pockets

    Partial refunds explained: how to issue one, how long refunds take, and whether fees come back

    How partial refunds work for online payments: issuing one, how long a refund takes, why processing fees are not refunded, refund deadlines and disputes.

  53. Hand-drawn illustration of a chat bubble holding a pay/plink link, an envelope and a QR code card, each with an arrow to a $99.00 checkout, and a person walking towards it

    What is a payment link? How to create one and get paid without building a checkout

    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.

  54. Hand-drawn illustration of a numbered payment receipt with a paid stamp, an envelope flying off it and a printer, next to a person with folded arms

    Payment receipts for online payments: what to include, how to send one, and receipt vs invoice

    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.

  55. Hand-drawn illustration of an order list, a ledger and a bank statement joined by matching lines with ticks, and a person walking towards them

    Payment reconciliation: how to match orders, fees, refunds and payouts to your bank account

    A practical guide to payment reconciliation: match orders to payments, explain your balance with the ledger, tie payouts to bank deposits, and fix gaps.

  56. Hand-drawn illustration of a paid receipt, a wallet and a bank building connected by arrows, the wallet showing an available balance, and a person sitting on a stack of coins

    What is payment settlement? How money gets from a successful payment to your bank account

    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.

  57. Hand-drawn illustration of a fanned stack of test cards labelled 4242, 3220 and 0002 next to a ticked checklist, and a grinning person with folded arms

    Test credit card numbers for payment testing: every outcome, and what to test besides cards

    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.

  58. Hand-drawn illustration of an envelope bouncing off a server with a red cross, a retry timeline of 30s, 2m, 10m, 30m and 2h, and a magnifying glass, next to a worried person with hands in pockets

    Payment webhook not received? A checklist to find the cause and recover missed events

    Payment webhook not received? Check the delivery history, the URL, timeouts, signatures and subscriptions, then recover missed events from the events API.

  59. Hand-drawn illustration of a phone showing a QR code, a ¥268.00 total and a paid button, with Alipay and WeChat Pay labels pointing at it and a smiling person standing beside it

    How to accept Alipay and WeChat Pay online: a guide for international merchants

    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.

  60. Hand-drawn illustration of a checkout window with USD, HKD and CNY currency buttons and card, Alipay, WeChat Pay and PayPal options, next to a globe and a person pointing at it

    How to accept international payments on your website: currencies, payment methods and fees

    How to accept international payments on your website: a multi-currency checkout, cards and wallets, what it costs, payouts and a go-live checklist.

  61. Hand-drawn illustration of a bank card with an arrow curving back over it and 0.9% written below, next to a worried person with folded arms

    What is a chargeback? Chargeback rate thresholds, evidence and what happens to the money

    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.

  62. Hand-drawn illustration of a receipt reading amount 2990, fee 135, net 2855, next to a person sitting on a stack of coins

    How cross-border payment fees are calculated: the formula, small orders and payout costs

    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.

  63. Hand-drawn illustration of an epay request slip listing pid, money and sign parameters, with a person pointing at it

    Integrating the epay (易支付) protocol: MD5 signatures, notifications and three common pitfalls

    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.

  64. Hand-drawn illustration of an ID card marked 18+ and a globe, with a smiling person walking towards them

    Can you accept international payments without a registered business? Rules, limits and payouts for individuals

    Individuals aged 18 or over can accept payments with KukoPay using their own ID: what to prepare, excluded categories, payment limits and payout rules.

  65. Hand-drawn illustration of three envelopes carrying the same event ID going into a database with a unique constraint, recorded once

    Duplicate payment webhooks: verify signatures and stay idempotent so you only fulfil once

    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.

  66. Hand-drawn illustration of a browser window whose address bar reads return?paid=1 with a question mark on the page, and a person eyeing it suspiciously

    return_url vs notify_url: why a payment redirect is not proof of payment

    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.