Skip to navigation
Payouts

Tracking Payouts

Monitor and review payout transactions

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 or the merchant-reference search (below). For ongoing status tracking, rely on webhooks rather than polling this list.

Example Request:

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:

[
  {
    "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:

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

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

Example Response:

{
  "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. For setup and delivery, see 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 for setup)
  • Store payout transactionIds 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.