> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leapfinancial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payout code (PIN)

> Get the cash-pickup PIN from GET /partner/operations/:id or the operation.references_available webhook

When the corridor issues a cash-pickup code, RaaS Widgets stores it as a canonical **`PAYOUT_CODE`** on the operation. You read it by pulling operation detail or by handling a dedicated webhook. You do not subscribe to corridor-internal events.

Auth: `X-API-Key` (`raas_sandbox_*` / `raas_live_*`). Host: [Partner API overview](/raas-widgets/api-reference/introduction).

<Warning>
  `PAYOUT_CODE` is a bearer instrument. Do not log the full value. Mask it in support tools.
</Warning>

The PIN is **independent of settlement**. It can appear while `status` is still `processing`, and it can arrive *after* `operation.completed`. Treat `GET /partner/operations/:operationId` as the source of truth.

<Tip>
  In sandbox, use magic amounts [`.77` (PIN while processing) and `.78` (PIN after completed)](/raas-widgets/ops/sandbox).
</Tip>

## Pull — GET operation detail

The [paginated list](/raas-widgets/ops/operations) does **not** include `references`. Fetch one operation:

```bash theme={null}
curl "$BASE_URL/partner/operations/op_acme_abc123" \
  -H "X-API-Key: raas_sandbox_your_api_key_here"
```

```json theme={null}
{
  "success": true,
  "data": {
    "operationId": "op_acme_abc123",
    "status": "processing",
    "references": [
      {
        "type": "PAYOUT_CODE",
        "value": "998877",
        "label": { "en": "Payout code", "es": "Clave de cobro" },
        "presentation": "PROMINENT",
        "issuedAt": "2026-08-27T06:40:00.000Z"
      },
      {
        "type": "TRACKING_REF",
        "value": "IMX-2026-00421",
        "presentation": "SECONDARY"
      }
    ],
    "documents": [
      {
        "kind": "PAYOUT_RECEIPT",
        "mediaType": "application/pdf",
        "freshness": "LIVE",
        "availability": "AVAILABLE"
      }
    ]
  }
}
```

```javascript theme={null}
const pin = (data.references ?? []).find((r) => r.type === 'PAYOUT_CODE');
if (pin) {
  // pin.value — persist on your order / show to the sender
}
```

If there is no `PAYOUT_CODE` yet, the corridor has not issued the code. Poll this GET, or wait for the webhook below.

<Tip>
  Typical pull cadence: after `operation.created` and `operation.completed`, and every 15–30 seconds while `status` is `processing` if your UX needs the PIN before settlement.
</Tip>

### Download the receipt PDF

`documents` are descriptors only. When `availability` is `AVAILABLE`:

```bash theme={null}
curl "$BASE_URL/partner/operations/op_acme_abc123/documents/PAYOUT_RECEIPT" \
  -H "X-API-Key: raas_sandbox_your_api_key_here" \
  -o receipt.pdf
```

The response is the raw PDF. Each call re-issues a live receipt.

## Push — `operation.references_available`

Configure your HTTPS endpoint in Partner Portal → **Settings → Webhooks**. Delivery uses the same `X-RAAS-*` HMAC as every other partner event — see [Webhook security](/raas-widgets/webhooks/security).

```json theme={null}
{
  "schemaVersion": 1,
  "event": "operation.references_available",
  "timestamp": "2026-08-27T06:40:00.000Z",
  "data": {
    "operationId": "op_acme_abc123",
    "linkId": "link_acme_a1b2c3d4e5f6",
    "userId": "usr_x9y8z7w6v5u4",
    "status": "processing",
    "references": [
      {
        "type": "PAYOUT_CODE",
        "value": "998877",
        "presentation": "PROMINENT"
      }
    ]
  }
}
```

<Steps>
  <Step title="Verify the signature">
    Reject unsigned bodies. Use the raw request bytes and the webhook secret from the Partner Portal.
  </Step>

  <Step title="Ack with 2xx">
    Return `200` immediately, then process asynchronously. Retries redeliver the same event.
  </Step>

  <Step title="Read PAYOUT_CODE">
    Find `data.references` where `type === "PAYOUT_CODE"` and persist `value` on your order.
  </Step>
</Steps>

```javascript theme={null}
app.post('/webhooks/raas-widgets', async (req, res) => {
  // verify X-RAAS-Signature first, then:
  const { event, data } = req.body;
  res.status(200).send('OK');

  if (event === 'operation.references_available') {
    const pin = (data.references ?? []).find((r) => r.type === 'PAYOUT_CODE');
    if (pin) await savePickupCode(data.operationId, pin.value);
    return;
  }
});
```

<Note>
  Acknowledge **unknown** events with HTTP `2xx`. This event is additive. A `switch` without a `default` that returns 200 will fail delivery retries.
</Note>

This webhook fires when the operation receives a non-empty `references` array. A documents-only update does not emit it — use GET detail for receipts.

## Use both

1. Handle `operation.references_available` for low latency.
2. On `operation.completed` (and while `processing` if needed), `GET /partner/operations/:id` and read `references`.

Do not assume `operation.completed` already contains the PIN. Settlement and enrichment are separate deliveries.

| Surface | PIN (`PAYOUT_CODE`) | Document descriptors | PDF bytes |
| - | - | - | - |
| `GET /partner/operations` (list) | No | No | No |
| `GET /partner/operations/:id` | Yes | Yes | No |
| `GET …/documents/PAYOUT_RECEIPT` | — | — | Yes |
| `operation.references_available` | Yes | Yes, if present | No |
| `operation.completed` | Maybe (only if already stored) | Maybe | No |

## Other `references[].type` values

Closed vocabulary. Ignore types you do not use.

| `type` | Typical use |
| - | - |
| `PAYOUT_CODE` | Pickup PIN |
| `TRACKING_REF` | Corridor tracking id for support |
| `FUNDING_REF` | Funding capture id (reconciliation) |
| `PAYER_LOCATOR` | Assigned payout location / agency locator |
| `BARCODE` | Barcode payload for cash-deposit funding |

Native corridor field names (`pinNumber`, `wireId`, …) are never exposed on the Partner API.

## Sandbox

On a **sandbox** partner, Intermex is not in the path. Use the cents of the amount you type (the anchored leg) to simulate PIN + receipt:

| Cents | Timing |
| -: | - |
| `.77` | PIN arrives \~3 s after accept, while `status` is still `processing` |
| `.78` | Operation completes first; PIN arrives \~6 s after accept |

Canned values (match the sample receipt PDF):

* `PAYOUT_CODE` — `40270384970766`
* `TRACKING_REF` — `445340485`

Then pull `GET /partner/operations/:id`, handle `operation.references_available`, and download `GET /partner/operations/:id/documents/PAYOUT_RECEIPT`. Other amounts do not emit a PIN. Host: [Partner API overview](/raas-widgets/api-reference/introduction).

## Next steps

<CardGroup cols={2}>
  <Card title="Operations API" icon="list" href="/raas-widgets/ops/operations">
    List and fetch operations.
  </Card>

  <Card title="Webhook events" icon="bell" href="/raas-widgets/webhooks/events">
    Full payload for `operation.references_available`.
  </Card>

  <Card title="Operation lifecycle" icon="diagram-project" href="/raas-widgets/ops/operation-lifecycle">
    `status` values vs webhooks.
  </Card>

  <Card title="Webhook security" icon="shield" href="/raas-widgets/webhooks/security">
    HMAC verification.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.