> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.crisscross.money/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.crisscross.money/_mcp/server.

# Tracking Payouts

Tracking payouts is essential for monitoring transaction status, auditing, and ensuring successful delivery of funds to recipients.

## Payout Status

Payouts can have the following statuses:

* **PENDING**: Payout has been created and is awaiting processing
* **PROCESSING**: Payout is currently being processed
* **COMPLETED**: Payout has been successfully completed
* **FAILED**: Payout has failed (check failure reason for details)
* **CANCELLED**: Payout was cancelled

## Viewing Payout History

You can retrieve payout history in a few ways. Use **Get Multiple Payouts** for filtered lists, and **Get Payout by ID** for a single payout record.

### Get Multiple Payouts

Use `GET https://api.crisscross.money/v1/payout` to list payouts. It takes exactly one query parameter:

**Query Parameters:**

* `merchantIds` (required): Comma-separated list of merchant IDs (UUIDs) to list payouts for.

There are no further filters and no pagination — the endpoint returns up to the 100 most recent payouts for the given merchants. To find one specific payout, use [Get Payout by ID](#get-payout-by-id) or the merchant-reference search (below). For ongoing status tracking, rely on [webhooks](#webhooks-for-real-time-updates) rather than polling this list.

**Example Request:**

```bash
curl --request GET 'https://api.crisscross.money/v1/payout?merchantIds=YOUR_MERCHANT_ID' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

**Response** — a JSON array of full payout records. Alongside the identifiers and routing metadata, each record carries its complete state history:

```json
[
  {
    "transactionId": "9f8b7c6d-5e4a-4b2c-8d0e-1a2b3c4d5e6f",
    "merchantReference": "PAYOUT-2024-001",
    "currentState": "COMPLETED",
    "previousStates": ["RECEIVED", "ROUTED", "EXECUTED"],
    "paymentMethodId": "banktransfer",
    "paymentLocation": "NGA",
    "transactionType": "PAYOUT",
    "processorReference": "PROC-123456",
    "transactionStates": [
      { "state": "COMPLETED", "transitionedAt": "2024-01-15T10:35:00Z" }
    ]
  }
]
```

Each record includes:

* `transactionId`: Unique transaction identifier
* `merchantReference`: Your provided merchant reference
* `currentState` / `previousStates`: Current state name and the ordered list of prior states
* `transactionStates`: Detailed history of state transitions
* `amount`, `currency`, `paymentLocation`, `paymentMethodId`, `transactionType`: What was paid out, where, and how
* `processorReference`, `financialTransactionReference`: Processor-side references
* `batchPayoutId`: Batch identifier, present when the payout was part of a batch

Note this is a fuller shape than the single-payout response below, which reports only the current state.

### Get Payout by ID

Use `GET https://api.crisscross.money/v1/payout/{transactionId}` to retrieve detailed information about a specific payout by its transaction ID.

**Example Request:**

```bash
curl --request GET 'https://api.crisscross.money/v1/payout/9f8b7c6d-5e4a-4b2c-8d0e-1a2b3c4d5e6f' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

**Response:** The payout's current state — the same shape returned when you initiate a payout and delivered on payout webhooks (see [Response Fields](#response-fields) below).

> **Note:** To find a payout by your own reference instead, use `GET /v1/payout/search?merchantIds=...&merchantReference=...`.

### Get Batch Payouts by Batch ID

Use `GET https://api.crisscross.money/v1/payouts/bulk/{batchId}` to retrieve the payouts that belong to a batch.

**Example Request:**

```bash
curl --request GET 'https://api.crisscross.money/v1/payouts/bulk/batch_1234567890' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

**Example Response:**

```json
{
  "batchId": "batch_1234567890",
  "payouts": [
    {
      "transactionId": "payout_abc123",
      "status": "PENDING",
      "message": "Payout transaction initiated successfully",
      "merchantReference": "PAYOUT-001"
    },
    {
      "transactionId": "payout_def456",
      "status": "FAILED",
      "message": "Invalid phone number format",
      "merchantReference": "PAYOUT-002"
    }
  ],
  "total": 2
}
```

## Webhooks for Real-Time Updates

Instead of polling the history endpoints, you can set up webhooks to receive real-time notifications when payout status changes. Webhooks are more efficient and provide immediate updates.

**Webhook events for payouts:**

* `payout.completed` - Payout was successfully delivered to the recipient
* `payout.failed` - Payout failed (e.g. invalid recipient account)
* `payout.errored` - Payout encountered a retryable error
* `payout.cancelled` - Payout was cancelled
* `payout.expired` - Payout expired

There is no creation event — notifications begin when the payout first reaches a reportable state change. Note that `payout.errored` is not terminal: an errored payout can retry and later emit `payout.completed` or another terminal event. The payload is the full transaction object, the same one returned when you poll for status.

For event types and payload examples, see [Webhook Events](/webhook-events). For setup and delivery, see [Webhooks](/core-concepts-webhooks).

## Use Cases

* **Audit Trail**: Track all payout transactions for accounting and compliance
* **Status Monitoring**: Check if payouts have been completed successfully
* **Troubleshooting**: Investigate failed payouts and understand failure reasons
* **Reporting**: Generate reports on payout activity over time periods
* **Reconciliation**: Match payouts with your internal records

## Response Fields

The single-payout response — returned by Initiate Payout and Get Payout by ID, and delivered on payout webhooks — includes:

* `transactionId`: Unique transaction identifier
* `status`: Current status
* `message`: Human-readable status message
* `merchantReference`: Your provided merchant reference
* `paymentMethodId`: Payment method (e.g. `banktransfer`, `mobilemoney`)
* `authState`: State detail object — `state` and `transitionedAt` always; on failures and errors also `message` and `code` (take the failure reason from here)
* `processorName`, `processorReference`, `financialTransactionReference`: Processor details, once assigned
* `batchPayoutId`: Batch identifier, present when the payout is part of a batch

## Best Practices

* Implement webhooks for real-time status updates rather than polling the list endpoint (see [Webhooks](/core-concepts-webhooks) for setup)
* Store payout `transactionId`s so you can look payouts up directly by ID
* Reconcile against your own references with `GET /v1/payout/search?merchantIds=...&merchantReference=...`
* Monitor failed payouts and take the failure reason from `authState.code` and `authState.message`

For detailed API documentation, see the [Payouts API Reference](/api-reference/payouts).