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