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

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 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

  9. 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.

  10. 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.

  11. 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.

  12. 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.

  13. 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.

  14. 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.

  15. 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.

  16. 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.

  17. 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.

  18. 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.

  19. 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.

  20. 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.

  21. 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.

  22. 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.

  23. 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.

  24. 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.

  25. 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.

  26. 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.

  27. 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.

  28. 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.

  29. 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.

  30. 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.

  31. 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.

  32. 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.

  33. 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.

  34. 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.