Accept a payment: cards, APMs and 3-D Secure 2

The payment lifecycle

A payment moves through a small state machine. Only two states are final, and only one of them means you have money. Everything your order system does should be driven by these transitions rather than by the response to the call that created the object.

Creating a payment

The same POST /v1/payments creates every kind of charge. Below is a card authorisation held for later capture, which is the shape most physical-goods merchants want.

# card charge, authorise now and capture on dispatchcurl -X POST https://api.bazpay.com/v1/payments \  -H "Authorization: Bearer sk_test_9f2c…" \  -H "Idempotency-Key: ord_10482" \  -d '{        "amount": 8990,        "currency": "EUR",        "method": "card",        "token": "tok_1Hq8Vc4nRs",        "capture": "manual",        "reference": "ORDER-10482",        "customer": { "email": "[email protected]" },        "return_url": "https://shop.example/thanks"      }'

token comes from hosted fields in the browser; your server never sees the PAN. Omit capture to take the money immediately.

The fields that change behaviour

• amount Integer, minor units. 8990 with EUR is 89.90 euro. Currency decides the exponent — JPY has none, so 8990 there is 8,990 yen.
• capture automatic takes the money at authorisation. manual holds it, which is correct whenever you might not ship.
• reference Your order id. It travels onto the payer's statement where the scheme allows, onto every event, and onto the settlement line — which is what makes reconciliation cheap.
• customer.email Optional but strongly advised: it feeds the risk score and is one of the data points that earns a transaction risk analysis exemption.
• return_url Required for any method that redirects. It must be HTTPS and must tolerate being opened twice.

Where the card form lives

This is the decision that fixes your PCI scope, so make it before you write checkout code. All three options keep you at SAQ A because the card number never reaches your systems in any of them — what changes is how much of the interface you own.

The EU method matrix

Every method below is created through the same call and reports the same events. They differ in three ways that affect your business rather than your code: how fast money settles, whether a partial refund is possible, and who carries the risk if the payer disputes it.

Show methods by the payer's country, not by your own. A Dutch checkout without iDEAL loses conversion no card optimisation will recover, and a Polish one without BLIK looks foreign. If you would rather not maintain that mapping, the hosted checkout does it from the payer's billing country and IP.

Pricing per method, including interchange++ breakdowns: pricing · method-level product detail: card and APM processing.

3-D Secure 2 and exemptions

Under PSD2, an electronic payment in the EEA needs strong customer authentication unless an exemption applies. We run 3-D Secure 2.2 for you: the authentication request is built, submitted and interpreted on the gateway, and you get the outcome on the payment object.

Frictionless is the normal case

Most authentications never show the payer anything. The issuer receives around 150 data points about the transaction, scores it, and returns an approval without a challenge. A challenge — a banking-app prompt or a one-time code — is the exception, and each one costs conversion.

Asking for an exemption

Where the rules allow it, you can ask to skip authentication. The issuer decides; a request is never a guarantee, and the response tells you what actually happened.

# ask for an exemption; the issuer may still force a challenge"sca": {  "request": "exemption",  "reason": "transaction_risk_analysis"}​# what came back on the completed payment"sca": {  "applied": "exemption",  "reason": "transaction_risk_analysis",  "liability_shift": false,  "version": "2.2.0"}

Capture, cancel, refund

An authorisation is a hold, not a payment. Three calls resolve it, and choosing the right one is the difference between a clean ledger and a support queue.

# capture less than you authorised — the rest is releasedPOST /v1/payments/pay_3fJ2Qk8vTn/capture  { "amount": 7490 }→ 200  { "status": "succeeded", "amount_captured": 7490 }​# nothing shipped — release the hold instead of refundingPOST /v1/payments/pay_3fJ2Qk8vTn/cancel→ 200  { "status": "canceled", "amount_captured": 0 }

• capture Takes the money, in full or in part. Capturing less releases the remainder to the payer's available balance straight away.
• cancel Releases an uncaptured hold. Use this — not a refund — when nothing shipped: it costs nothing and never appears on the payer's statement.
• refund Returns captured money over the original rail. Full or partial, and repeatable up to the captured amount.

The windows that matter

• A card authorisation expires after 7 days, or 30 for travel and lodging categories. Capture before then or it lapses.
• Card refunds are possible for 180 days after capture. Beyond that the money has to move as a payout.
• Bank-rail refunds have no scheme deadline but need the original payment to still be on file — we hold that for 7 years.
• A partial capture cannot be topped up. If you may ship more later, authorise the larger amount and capture down.

Reading a decline

A failed payment carries two codes: ours, which is stable and safe to branch on, and the issuer's raw reason, which is more specific but varies by bank. Show the payer a plain sentence, log both, and let the pair drive your retry policy.

Forcing each of these codes on demand in test mode: sandbox behaviour and test data.