Payout code (PIN)

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.

PAYOUT_CODE is a bearer instrument. Do not log the full value. Mask it in support tools.

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.

In sandbox, use magic amounts .77 (PIN while processing) and .78 (PIN after completed).

Pull — GET operation detail

The paginated list does not include references. Fetch one operation:

curl "$BASE_URL/partner/operations/op_acme_abc123" \
  -H "X-API-Key: raas_sandbox_your_api_key_here"

{
  "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"
      }
    ]
  }
}

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.

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.

Download the receipt PDF

documents are descriptors only. When availability is AVAILABLE:

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.

{
  "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"
      }
    ]
  }
}

Verify the signature

Reject unsigned bodies. Use the raw request bytes and the webhook secret from the Partner Portal.

Ack with 2xx

Return 200 immediately, then process asynchronously. Retries redeliver the same event.

Read PAYOUT_CODE

Find data.references where type === "PAYOUT_CODE" and persist value on your order.

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;
  }
});

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

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

Handle operation.references_available for low latency.
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.

Next steps

Operations API

List and fetch operations.

Webhook events

Full payload for operation.references_available.

Operation lifecycle

status values vs webhooks.

Webhook security

HMAC verification.

Getting Started

Request API

Concepts

Integration

Flows

Webhooks

Operations

Pull — GET operation detail

Download the receipt PDF

Push — `operation.references_available`

Use both

Other `references[].type` values

Sandbox

Next steps

Operations API

Webhook events

Operation lifecycle

Webhook security

​Pull — GET operation detail

​Download the receipt PDF

​Push — operation.references_available

​Use both

​Other references[].type values

​Sandbox

​Next steps

Operations API

Webhook events

Operation lifecycle

Webhook security

Pull — GET operation detail

Download the receipt PDF

Push — `operation.references_available`

Use both

Other `references[].type` values

Sandbox

Next steps