Integrating an instant payment rail. 6 chapters and a final quiz.

Chapter 1. Push or request to pay: choosing the initiation model.

An instant rail has no authorization and no capture: the payment either goes or it doesn't. With no intermediate step, the design must settle up front who triggers the payment. In the push model, the payer initiates from their banking app and the payee learns of the credit after the fact. In the request to pay model, the payee sends a request that the payer approves. The code differs, the reconciliation differs, and so does the abandonment rate.

• Remote sales with a shopping cart: request to pay or a dynamic QR code, so the order reference travels with the payment
• In-store payments: a merchant-presented QR code, or a contactless tap where the rail supports it (Pix por Aproximação in Brazil)
• B2B invoices: request to pay, the only model that carries the due date and amount without rekeying
• Payouts (refunds, payroll, claims): pure push; the business becomes the payer and the rail works like an ordinary credit transfer
• Subscriptions: a recurring mandate, with authorization and revocation rules specific to each market

One question decides the model: does the payee know the amount before the payment? If so, a request to pay or a dynamic QR code removes manual entry, and with it wrong amounts and lost references. If not (a donation, a top-up, a partial payment), free-form push is the only option, and the integration must match unexpected credits to open receivables, a problem covered in chapter 4.

Chapter 2. Addressing: from alias to account, without paying the wrong person.

Nearly every modern instant rail has replaced account details with an alias: a mobile number, a national ID, an email address, or a random string. A central directory resolves the alias to an account at payment time. The extra step looks harmless. In practice, it shifts part of the risk to the integrator, who must decide what to do when the lookup returns anything other than “yes.”

def resolve_alias(alias, expected_name, amount):
    # 1. Never cache persistently: holders can reassign an alias.
    #    Resolve on every payment, even for a known customer.
    r = directory.resolve(alias, timeout_ms=800)

    if r.status == "NOT_FOUND":
        return Decline("unknown alias", retryable=False)

    if r.status == "UNAVAILABLE":
        # Directory outage: do NOT guess. Offer manual account entry.
        return Decline("directory unavailable", retryable=True)

    # 2. Name check: compare, don't trust.
    score = compare_names(r.holder_name, expected_name)
    if score == "MISMATCH":
        return Decline("different account holder", retryable=False)
    if score == "CLOSE":
        # Gray zone: show the returned name and require confirmation.
        return Confirmation(displayed_name=r.holder_name)

    # 3. Log the resolved (alias, account, timestamp) tuple.
    #    This record is what will defend the case in a dispute.
    log.write(alias, r.account, r.holder_name, now())
    return Ok(r.account)

• Never cache an alias long-term: the holder can delete or reassign it at any time, and the rail notifies no one
• Treat a directory outage as a retryable decline, distinct from an unknown alias: each calls for the opposite response
• Show the returned name before confirmation, even when the rail doesn't require it, because it's the only check the payer can make
• Log the resolution with a timestamp: without that record, no dispute can be defended
• Count the characters: a hand-keyed alias can be off by one digit, and the rail will execute a perfectly valid payment to a stranger

Chapter 3. Notifications and idempotency: the asynchronous contract behind real time.

On an instant rail, the notification is everything. There is no clearing file the next morning, no intermediate status to query, no delayed capture. The credit lands, a message reports it, and the payee's system acts. Yet two clocks are running, and confusing them is the most common integration mistake. The rail's clock runs in seconds; the clock for the notification delivered to the merchant depends on a queue, a network, and a server.

• Deduplicate on the rail ID, not the message ID: the first is unique to each payment and stable; the second belongs to the delivery layer
• Check the amount received against the amount expected: with free-form push, the payer decides what to send, and a payment one cent short is not a settlement
• Handle out-of-order events: on request-to-pay rails, the response and the credit travel separately and sometimes arrive in reverse order
• Set a silence timeout: once the scheme's own time limit has passed, query the status API rather than keep waiting, because a missing message is not neutral information
• Make business processing replayable: delivery is guaranteed at least once, so duplicates are the normal case, not an incident

app.post("/notifications/instant", async (req, res) => {
  if (!verifySignature(req.rawBody, req.headers)) {
    return res.status(400).send("invalid signature");
  }
  const evt = JSON.parse(req.rawBody);

  // Dedup key = the RAIL's end-to-end ID.
  // Pix: endToEndId. ISO 20022: EndToEndId in the pacs.008. UPI: UPI
  // transaction ID. The PSP's event ID, by contrast, changes on redelivery.
  const isNew = await db.credits.insertIfAbsent({
    railId: evt.endToEndId,
    amount: evt.amount,
    currency: evt.currency,
    receivedAt: new Date(),
  });
  if (!isNew) return res.status(200).send("already processed");

  // A payer can send less, or more, than the expected amount.
  const order = await db.orders.byReference(evt.reference);
  if (!order || order.amountDue !== evt.amount || order.currency !== evt.currency) {
    await queue.enqueue("credit-to-review", evt); // manual review
    return res.status(200).send("ok");
  }

  await queue.enqueue("release-order", { order: order.id, credit: evt.endToEndId });
  return res.status(200).send("ok");
});

The silence timeout needs an explicit setting. The European Payments Council's SEPA Instant Credit Transfer rulebook sets a maximum execution time of 10 seconds, with a time-out deadline of 20 seconds in exceptional circumstances. A system that waits 30 minutes before raising a flag has already lost its customer; one that retries after two seconds creates duplicates. Base the value on the scheme, not on a hunch.

Chapter 4. Real-time reconciliation: the ID that carries everything.

On an instant rail, reconciliation is no longer an overnight batch. It becomes an online check that runs while the customer waits for the confirmation screen. It hinges on a single element: an ID that travels with the payment from initiation to the account statement. Choosing it, generating it in the right place, and storing it correctly is most of the work. The rest is a join.

E 12345678 202603151432 a1b2c3d4e5f
| |        |            |
| |        |            +-- 11 alphanumeric characters, generator's sequence number
| |        +--------------- yyyyMMddHHmm in UTC (12 characters)
| +------------------------ ISPB of the agent that generated it, or first 8 digits
|                           of the initiating provider's CNPJ (8 digits)
+-------------------------- literal "E"

Binding rules (Manual de Padroes para Iniciacao do Pix, BCB):
  - strict uniqueness: never send the same value to the SPI twice
  - the sequence number must be unique within a given minute yyyyMMddHHmm
  - 12-hour tolerance, early or late, relative to actual processing

• Reconcile at three points: the receivable in the merchant's books, the credit reported by the PSP, and the line on the settlement account statement
• Put a unique constraint in the database on the rail ID: a technical constraint beats application-level vigilance
• Keep the reference even after a rejection: a rejected payment that is resent gets a new ID, and only the payee holds the link between the two
• Measure the lag between notification and statement: a growing lag signals a stuck queue at the PSP before the customer complains
• Handle orphan credits in a dedicated queue, with a stated processing time: an instant transfer without a reference is still a payment you must honor

Free-form push inevitably produces credits with no usable reference: the payer sent the money from their app without copying the order number. Three levers reduce the problem. The first is a short, readable reference that the payer can copy without mistakes. The second is a virtual account per customer, when the PSP offers one, so the credited account identifies the payer. The third is to switch to a QR code or a request to pay, both of which carry the reference automatically.

Chapter 5. Irrevocability: refunds and disputes without chargebacks.

An accepted instant transfer is final. No network reverses it, no dispute window opens, and no reason code brings it back. The merchant is rid of chargebacks but loses the ability to cancel. Two distinct operations must therefore be built separately. A refund is decided by the payee; a dispute is raised by the payer with their own provider. Many integrations confuse the two.

PUT /v2/pix/{e2eid}/devolucao/{id}
Host: api-pix.example.com.br
Content-Type: application/json

{
  "valor": "120.50",
  "natureza": "ORIGINAL",
  "descricao": "Devolucao pedido 2026-4471"
}

# Before calling:
#   - {e2eid} is the endToEndId of the Pix payment RECEIVED, not of the refund
#   - {id} is generated by the payee's system and serves as the idempotency key:
#     replaying the same {id} does not create a second refund
#   - total refunds cannot exceed the amount received
#   - the reason code on the pacs.004 will be MD06 for a standard Pix payment

• Deterministic refund ID: derive {id} from the order, never from a counter or a random value, so that a replay after an incident is harmless
• Running-total check: add up the partial refunds already issued before authorizing another
• Separation of duties: above a set threshold, the person who enters a refund is not the one who approves it
• Full traceability: from a sale, find every refund; from a refund, find the sale
• Honest timelines: tell the customer the rail's actual timing, not a card-style delay of several business days

Customer-facing messaging deserves the same rigor as the code. Promising “protection” on an instant rail invites claims the rail doesn't cover. Brazil's MED returns whatever remains in the fraudster's account and nothing more, while the UK regime is capped at £85,000 and applies only to eligible payments. In the US, no federal law requires reimbursement of authorized push payment fraud. Describing the actual protections, limits included, costs less than a dispute.

Chapter 6. Failures, limits, and pre-launch testing.

An instant payment can fail in four ways, and only one looks like a card decline. An explicit rejection returns a code; an expiry closes a request to pay that got no response; an exceeded limit blocks the payment before it even reaches the rail. Silence, finally, returns nothing at all. Handling all four with the same retry logic produces double payments, which on an irrevocable rail must be recovered by hand.

Then there is the question of access to the rail, which drives the timeline far more than the code does. In India, direct access to UPI is reserved for banks, and a fintech operates as a TPAP under a sponsor bank. In Brazil, a payment institution can join the SPI. In Turkey, payment institutions and e-money institutions participate directly in FAST. The answer shapes margins, dependencies, and lead times. Settle it before the first line of code, not after testing.