Integrating a PSP from A to Z. 6 chapters and a final quiz.

Chapter 1. Scoping the project and choosing a PSP.

Integrating a payment service provider (PSP) is a project that commits a company's cash flow, compliance and customer experience for years, well beyond plugging into an API. Scoping comes before code. It covers the countries served, the payment methods expected, the projected volume, and the sales model (direct sales, subscriptions, marketplace). This scoping should drive the choice of provider far more than how polished its documentation looks.

What a PSP (really) does

• Collects payment data in a PCI DSS–compliant environment, so the merchant does not have to
• Routes transactions to one or more acquirers and to the card networks (France's domestic CB scheme, Visa, Mastercard…)
• Orchestrates the 3-D Secure authentication that PSD2 requires in Europe
• Aggregates local payment methods: wallets, bank transfers, BNPL, iDEAL, Pix, Wero…
• Reports: dashboard, settlement reports, reconciliation exports, dispute management
• Pays out funds to the merchant's account, net of fees

The criteria that matter

Chapter 2. Working with the sandbox, API keys, and secrets.

Every serious PSP provides a sandbox: an isolated test environment with no real money that mirrors the production API, and where your team will spend its first few weeks. Start by creating the test account and generating the API keys. Then deliberately trigger every scenario (success, decline, 3-D Secure, expiry) before you even think about the happy path.

• Test cards: 4242 4242 4242 4242 (success at Stripe) and its variants that simulate a decline, insufficient funds, a stolen card, or a 3DS failure
• Simulated 3-D Secure: mock challenge pages to test frictionless and challenge flows without a real bank
• Test webhooks: replayable on demand from the dashboard, essential for chapter 4
• Dummy data: test IBANs, magic amounts that trigger specific behavior (e.g., an amount that forces a decline)
• Sandbox dashboard: the same screens as in production, to train support and accounting before go-live

curl https://api.psp.example/v1/payments \
  -u "sk_test_51Hxxxxxxxxxxxx:" \
  -d amount=4990 \
  -d currency=eur \
  -d "payment_method_types[]=card" \
  -d "metadata[order_id]=ORD-2026-1042"

One last point of method: treat the sandbox as a full-fledged environment, with its own versioned configuration. Teams that get go-live right maintain strict parity between test and production: the same API versions, the same webhook subscriptions, the same currencies, with just one difference, the key prefix (sk_test_ versus sk_live_).

Chapter 3. Creating a payment: from intent to authorization.

Modern payment APIs are built on the payment intent pattern. The merchant's server first declares the amount it wants to collect, and the PSP returns an ID and a client secret. The browser then confirms the payment with the card data, which never passes through the merchant's server. This two-step split absorbs 3-D Secure authentication and asynchronous payment methods.

{
  "id": "pay_9f2b7c4e",
  "object": "payment",
  "amount": 4990,
  "currency": "eur",
  "status": "requires_action",
  "next_action": { "type": "redirect_to_3ds" },
  "client_secret": "pay_9f2b7c4e_secret_Ab12Cd34",
  "metadata": { "order_id": "ORD-2026-1042" }
}

• Idempotency key on creation: send a unique Idempotency-Key header per order; after a network timeout, replaying the request with the same key will not create a second payment
• Amount recalculated on the server: never use an amount from the browser, which a savvy customer can tamper with
• Currency in ISO 4217 (eur, usd, jpy), consistent with the settlement account
• `metadata.order_id` every time: it is the thread that ties together the payment, the order and accounting reconciliation
• A clean `return_url`: the return page shows “payment being confirmed” and validates nothing itself

Chapter 4. Handling webhooks reliably, with mandatory idempotency.

A modern payment is asynchronous by nature: 3-D Secure can take two minutes, a bank transfer two days, a dispute two months. The PSP notifies you of every status change by webhook, an HTTP POST request to your server. This channel carries the entire integration, and it is also where most production incidents start: webhooks lost, processed twice, or received out of order.

The five golden rules of a webhook consumer

• Verify the signature on the raw request body (before any JSON parsing): otherwise anyone can send you a fake payment.captured
• Respond 2xx fast (< 5 s): PSPs treat any other code or a timeout as a failure and redeliver the notification
• Process in an asynchronous queue: acknowledge first, work later, and never send emails or call the ERP inside the HTTP handler
• Deduplicate by event ID: delivery is guaranteed at least once, so duplicates are normal, not exceptional
• Tolerate out-of-order events and reconcile: a payment.captured can arrive before the payment.authorized; when in doubt, query the API (GET /payments/{id}), which remains the source of truth

app.post("/webhooks/psp", async (req, res) => {
  // 1. Signature on the raw body — reject without processing if invalid
  const signature = req.headers["psp-signature"];
  if (!verifyHmacSha256(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(400).send("invalid signature");
  }

  const event = JSON.parse(req.rawBody);

  // 2. Idempotency: event.id is UNIQUE in the database.
  //    If the insert fails, the event was already received.
  const inserted = await db.webhookEvents.insertIfAbsent({
    id: event.id,
    type: event.type,
    receivedAt: new Date(),
  });
  if (!inserted) {
    return res.status(200).send("duplicate ignored"); // already processed: 200 anyway
  }

  // 3. Acknowledge fast, process asynchronously
  await queue.enqueue(event);
  return res.status(200).send("ok");
});

Chapter 5. Modeling the state machine, capture, and refunds.

A payment moves through a state machine, whereas a simple “paid / not paid” boolean would distinguish only two positions. Modeling it explicitly in your code, with the list of allowed transitions, remains the best antidote to integration bugs. It then becomes impossible to refund a payment that was never captured, or to ship an order still waiting on 3DS.

type PaymentStatus =
  | "created"          // intent created, waiting for the customer
  | "requires_action"  // 3-D Secure or redirect in progress
  | "authorized"       // funds held at the issuer, nothing collected yet
  | "captured"         // capture requested: collection has started
  | "settled"          // funds settled to the merchant (D+1 to D+3)
  | "failed"           // issuer decline, 3DS failure, expiry
  | "canceled"         // void before capture
  | "refunded";        // refunded, fully or partially

const transitions: Record<PaymentStatus, PaymentStatus[]> = {
  created: ["requires_action", "authorized", "failed"],
  requires_action: ["authorized", "failed", "canceled"],
  authorized: ["captured", "canceled"],
  captured: ["settled", "refunded"],
  settled: ["refunded"],
  failed: [],
  canceled: [],
  refunded: [],
};

function assertTransition(from: PaymentStatus, to: PaymentStatus): void {
  if (!transitions[from].includes(to)) {
    throw new Error("Forbidden transition: " + from + " -> " + to);
  }
}

Capture now or later?

Voiding is not refunding

As long as the payment is only authorized, you can void it, a free and near-instant operation that lifts the hold at the issuer before any money has moved. Once it is captured, you have to refund it. A reverse money flow goes back to the customer's card and takes 3 to 10 days to show up on their statement, and the PSP generally does not return the original fees.

• Partial refund: several successive refunds are possible, up to the amount captured, never beyond
• Dispute after a refund: a customer can open a chargeback even after a refund has been issued; keep proof of the refund for representment
• Traceability: each refund has its own ID, to be linked to the order_id for accounting reconciliation

Chapter 6. Going live with a test checklist.

Prepare a payment integration's move to production like a house move: anything that has not been tested will break in transit. Go-live is not an event, it is a process. It happens as a phased rollout, under close monitoring, with the ability to roll back at every step.

The test checklist

• ✅ Standard card payment: authorization, capture, webhook, confirmation email, accounting entry
• ✅ 3-D Secure: frictionless AND challenge flows, plus abandonment mid-challenge
• ✅ Issuer decline: clear customer message, no order created, option to retry
• ✅ Network timeout on creation: replay with the same idempotency key → a single payment
• ✅ Webhooks: invalid signature rejected, duplicate cleanly ignored, out-of-order events absorbed
• ✅ Full and partial refunds, including a failed refund
• ✅ Amounts: cents verified, zero-decimal currency (JPY) if relevant, server amount ≠ client amount rejected
• ✅ State machine: every forbidden transition raises an error
• ✅ Monitoring: alerts on a drop in authorization rate, on webhook failures, on a growing processing queue
• ✅ Reconciliation: the PSP's settlement report is automatically matched against orders