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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.juicefin.com/apis/transactions/connecting-auth-to-purchase.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.