Payment API integration: a step-by-step guide for developers

A payment API integration connects your application to a payment provider so it can create payments, redirect or embed checkout, receive results and handle refunds programmatically. A solid integration has five parts: a clear model of your payment flows, securely stored API keys, a checkout that keeps card data off your servers, webhook handling that is verified and idempotent, and reconciliation that proves every payment landed.

This guide walks through those parts in the order you'll build them, with notes for South African providers and payment methods.

Step 1: map your payment flows before writing code

List every way money moves in your product. Most businesses have more than they think:

For each flow, write down who initiates it, which system is the source of truth for the amount, and what should happen when it fails. This document becomes your test plan later.

Step 2: choose between a direct gateway API and a platform layer

You can integrate directly with one gateway's API, or with a billing platform that connects to several gateways.

• Direct gateway integration gives you full control and fewer moving parts if you'll only ever use one provider. You'll build invoicing, subscriptions, retries and reconciliation yourself.
• A platform layer gives you one API for invoices, subscriptions and checkout across several gateways, at the cost of adding another dependency.

Neither is universally better. If you're unsure which gateways suit you, start with how to choose a payment gateway in South Africa.

Step 3: set up authentication and key storage

Payment APIs typically authenticate server-to-server requests with secret API keys. Treat them like passwords:

• Keep them in environment variables or a secrets manager, never in source code or front-end bundles.
• Use separate keys for sandbox and production.
• Give each service its own key so you can rotate one without breaking others.
• Restrict who can view or create keys in the provider's dashboard.

Our API key security guide covers rotation and leak response in more depth.

Step 4: build the checkout without touching card data

The safest pattern for most businesses is to let the provider handle card entry through a hosted payment page or a provider-hosted field, and never let raw card numbers pass through your servers. This keeps your PCI DSS scope much smaller. PCI DSS v4.0.1 is the current version as of September 2026; check the PCI Security Standards Council and your acquirer for which self-assessment questionnaire applies to you.

A typical server-side flow:

1. Your server creates a payment or checkout session with the provider, passing the amount in cents (or the provider's required format), currency (ZAR), your own reference and return URLs.
2. The provider returns a URL or session reference.
3. You redirect the customer or load the provider's embedded component.
4. The customer pays; the provider redirects them back to your return URL.
5. You don't mark anything as paid yet. The return redirect can be faked or interrupted.

Amounts deserve care. Use integer cents or a decimal type, never floating point:

// R1,450.00 as integer cents avoids floating-point rounding errors.
const amountCents = 145000;
const display = (amountCents / 100).toLocaleString("en-ZA", { style: "currency", currency: "ZAR" });

Step 5: confirm payments with webhooks and verification

The provider notifies your server of the final result through a webhook. Your handler should verify the signature, store the event, acknowledge quickly, and then confirm the transaction status and amount through the provider's API before fulfilling the order. Our guide to payment webhooks sets out ten practices worth following.

Step 6: make every write safe to retry

Networks fail mid-request. If your server times out after asking the provider to create a charge or refund, you don't know whether it succeeded. Where the API supports idempotency keys, send a unique key per logical operation and reuse it on retry. Where it doesn't, look up the operation by your own reference before trying again.

Step 7: handle failure paths deliberately

Write down what happens for each of these, and test them in sandbox:

• Card declined or 3-D Secure authentication failed
• Customer abandons checkout
• Webhook delayed by several minutes
• Duplicate webhook
• Partial refund followed by a full refund request
• Debit order returned unpaid days after collection
• Provider API returns 5xx or times out

Step 8: test, then go live in stages

1. Run every flow in the provider's sandbox, including failures.
2. Confirm your logs never contain card numbers, CVVs or secret keys.
3. Switch to production keys and process a small real transaction yourself; refund it.
4. Release to a small group of customers first.
5. Monitor webhook failures, error rates and reconciliation exceptions daily for the first few weeks.

Step 9: reconcile daily

Compare successful payments in your database with the provider's settlement report and your bank statement every day. Differences caught within a day are easy to fix; differences found at month-end are expensive.

A payment API integration checklist

• Keys in a secrets manager, separate per environment
• No card data on your servers or in logs
• Webhook signatures verified; payments re-verified via API
• Idempotent handling of retries and duplicate events
• Amounts stored as integer cents or decimals
• Refunds and unpaids tested end to end
• Daily reconciliation job and alerting in place

How CentraPoint helps

CentraPoint offers a REST API authenticated with API keys, so you can create customers, invoices, payment links and hosted checkout sessions once and collect through whichever gateways you enable (PayFast, Paystack, Peach Payments, Ozow, Yoco, Netcash, Flutterwave, M-Pesa and more). Inbound gateway webhooks are signature-checked and re-verified server-side, outbound webhooks notify your systems, and an entitlements API tells your app what a subscriber has access to. Start with the quickstart.

Frequently asked questions

How long does a payment API integration take?

A simple once-off checkout with one provider can take days; subscriptions, refunds, multiple gateways and reconciliation take considerably longer. Your list of payment flows is the best predictor.

Do I need to be PCI DSS compliant if I use a hosted checkout?

Most merchants that accept cards still have PCI DSS obligations, but a hosted page or provider-hosted fields usually reduce the scope. Confirm the applicable self-assessment questionnaire with your acquirer or gateway.

Should I mark an order as paid when the customer returns from checkout?

No. The return redirect can be interrupted or tampered with. Wait for a verified webhook and confirm the payment with the provider's API.

How should I store payment amounts?

Use integer cents or a fixed-precision decimal type. Floating-point numbers can introduce rounding errors that show up as one-cent reconciliation differences.