> For the complete documentation index, see [llms.txt](https://apidocs.juicefin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.juicefin.com/apis/transactions/connecting-auth-to-purchase.md).

# 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):

```jsonc
{
  "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](https://apidocs.juicefin.com/apis/transactions/decoding-an-iso-8583-payload).