Connecting Auth to Purchase

This page explains the two webhook event types, shows how to decode the embedded ISO 8583 message, and details a simple strategy for matching an Authorization (PP00DS) to its corresponding Purchase (PP10DS) by using the Retrieval Reference Number (RRN – field 37) that appears in both ISO messages.

---

1. Overview

Every card transaction you process triggers a real‑time webhook that looks like this (trimmed for clarity):

{
  "MessageType": "Transaction",
  "TransactionCode": "PP00DS",        // or PP10DS
  "TransactionDescription": "Authorization",
  "TransactionId": "4f8b8ec6‑…",
  "CardNumber": "6993",
  "Amount": "285",
  "TimeStamp": "2025‑07‑24 14:13:49",
  "ISOFullMessage": "ISO0260000700 120 …"  // full ISO 8583 payload
}

• PP00DS → Authorization hold

• PP10DS → Purchase / financial completion

Both payloads carry the processor’s raw ISO 8583 message (ISOFullMessage). By decoding that message we can extract immutable identifiers—especially field 37 (Retrieval Reference Number)—and use them to link the two webhooks that represent a single consumer action at the point of sale.

---

2. Anatomy of the Webhook

JSON field	Purpose
MessageType	Always "Transaction" for these webhooks.
TransactionCode	PP00DS (auth) or PP10DS (purchase).
TransactionDescription	Human‑readable counterpart of TransactionCode.
TransactionId	Internal UUID we assign when the webhook is generated.
ISOFullMessage	ASCII dump of the entire ISO 8583 message returned by the processor.

Other fields (CardNumber, Amount, TimeStamp, etc.) are useful for reconciliation but should not be used to join messages because they are not guaranteed unique.

---

3. ISO 8583 Primer (just what you need)

┌───────────────────────────────────────────┐
│ ISO0260000700 120 …                      │ ←  ISO header (varies by host)
│ 0120 / 0220                               │ ←  MTI: 0120 = Auth Advice, 0220 = Fin Advice
│ Primary bitmap (128‑bit)                  │
│ Field 2  → PAN (masked or omitted)        │
│ Field 11 → Systems Trace Audit # (STAN)   │
│ Field 37 → Retrieval Reference Number     │ ★ we care about this one
│ Field 41 → Terminal ID (matches JSON)     │
│ …                                         │
└───────────────────────────────────────────┘

• MTI (Message Type Indicator)

  • 0120 – Authorization advice (matches PP00DS)

  • 0220 – Financial advice (matches PP10DS)

• Field 37 – Retrieval Reference Number (RRN)

  • 12‑character string, globally unique for the life of the transaction

  • Identical in the authorization and the subsequent purchase

• Field 11 – STAN

  • 6‑digit Systems Trace Audit Number; also identical for the pair

  • Useful as a secondary key or debugging aid

---

4. Linking an Authorization to Its Purchase

1. Parse both incoming webhooks and store them in a temporary table/queue.

2. Decode ISOFullMessage and extract:

   • field_37 → rrn

   • (optional) field_11 → stan

3. Join on rrn (and optionally stan) to tie the PP00DS record to its corresponding PP10DS record.

Example (masked)

Event	MTI	STAN	RRN	Amount
Authorization	0120	185503	724181349863	285
Purchase	0220	583719	724181349863	285

Even though the approval codes differ (185503 vs 583719), the RRN (724181349863) is identical, proving they are the same transaction lifecycle.

---

5. Implementation Hints

Concern	Recommendation
Out‑of‑order delivery	Buffer messages for a few days; link retrospectively.
Partial captures	One auth can spawn multiple purchases; use both RRN and amount to decide if a purchase fully settles or partially captures the hold.
Reversals / voids	MTIs 0420/0421 (or 0221) will reference the same RRN—treat them as negative adjustments on the original auth.
Logging	Mask PANs (field 2) and redact any PII to remain PCI‑DSS compliant.

---

Need More?

• For a deeper dive into all ISO 8583 fields your processor sends, see Decoding an ISO 8583 Payload.