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/payouts/history to retrieve a list of payouts with filtering options:

Query Parameters:

• currency (optional): Filter by currency code (NGN, XOF, XAF, GHS, KES, ZAR, EGP, USDT, USDC)
• startDate (optional): Start date for filtering (ISO 8601 format, e.g., 2024-01-15T00:00:00Z)
• endDate (optional): End date for filtering (ISO 8601 format, e.g., 2024-01-31T23:59:59Z)
• status (optional): Filter by payout status (PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED)
• limit (optional): Maximum number of records to return (default: 50, max: 100)
• offset (optional): Number of records to skip (default: 0)

Date Format Examples:

• Full datetime: 2024-01-15T00:00:00Z (UTC)
• With milliseconds: 2024-01-15T00:00:00.000Z (UTC)
• Date range: startDate=2024-01-15T00:00:00Z&endDate=2024-01-31T23:59:59Z

Example Request:

$
curl --request GET 'https://api.crisscross.money/v1/payouts/history?currency=NGN&status=COMPLETED&startDate=2024-01-15T00:00:00Z&endDate=2024-01-31T23:59:59Z&limit=50&offset=0' \
>
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response:

1
{
2
  "payouts": [
3
    {
4
      "transactionId": "payout_9f8b7c6d5e4a3b2c1d0e",
5
      "status": "COMPLETED",
6
      "message": "Payout completed successfully",
7
      "merchantReference": "PAYOUT-2024-001",
8
      "payoutState": {
9
        "type": "completed"
10
      },
11
      "processorReference": "PROC-123456",
12
      "createdAt": "2024-01-15T10:30:00Z",
13
      "completedAt": "2024-01-15T10:35:00Z",
14
      "failureReason": null
15
    }
16
  ],
17
  "total": 1
18
}

Response fields:

• payouts: Array of payout objects
• total: Total number of payouts matching the filter criteria (use this to determine if more pages exist)

Each payout object includes:

• transactionId: Unique transaction identifier
• status: Current status (PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED)
• message: Status message
• merchantReference: Your provided merchant reference
• payoutState: Object with type field
• processorReference: Processor reference number
• createdAt: Creation timestamp (ISO 8601)
• completedAt: Completion timestamp (ISO 8601, null if not completed)
• failureReason: Reason for failure (only if status is FAILED)

Get Payout by ID

Use GET https://api.crisscross.money/v1/payouts/history/{id} to retrieve detailed information about a specific payout by its payout ID.

Example Request:

$
curl --request GET 'https://api.crisscross.money/v1/payouts/history/payout_9f8b7c6d5e4a3b2c1d0e' \
>
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response: Same structure as a single payout object (see Response Fields below).

Note: GET /payouts/{payoutId} is an alternative alias for the same single-payout lookup.

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:

1
{
2
  "batchId": "batch_1234567890",
3
  "payouts": [
4
    {
5
      "transactionId": "payout_abc123",
6
      "status": "PENDING",
7
      "message": "Payout transaction initiated successfully",
8
      "merchantReference": "PAYOUT-001"
9
    },
10
    {
11
      "transactionId": "payout_def456",
12
      "status": "FAILED",
13
      "message": "Invalid phone number format",
14
      "merchantReference": "PAYOUT-002"
15
    }
16
  ],
17
  "total": 2
18
}

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.created - Payout was created
• payout.completed - Payout completed successfully
• payout.failed - Payout failed

For webhook setup, event types, and payload examples, see the Webhooks guide.

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

Each payout in the history response includes:

• transactionId: Unique transaction identifier
• status: Current status (PENDING, PROCESSING, COMPLETED, FAILED, or CANCELLED)
• message: Status message
• merchantReference: Your provided merchant reference
• payoutState: Object with type field indicating payout state
• processorReference: Processor reference number
• createdAt: Timestamp when payout was created (ISO 8601 format)
• completedAt: Timestamp when payout completed (ISO 8601 format, present if status is COMPLETED)
• failureReason: Reason for failure (only present if status is FAILED)

Pagination

When retrieving multiple payouts, use limit and offset for pagination:

1. First page: limit=50&offset=0 (returns first 50 payouts)
2. Second page: limit=50&offset=50 (returns payouts 51-100)
3. Third page: limit=50&offset=100 (returns payouts 101-150)
4. Continue until offset >= total

Example pagination loop:

1
let offset = 0;
2
const limit = 50;
3
let hasMore = true;
4
5
while (hasMore) {
6
  const response = await fetch(
7
    `https://api.crisscross.money/v1/payouts/history?limit=${limit}&offset=${offset}`,
8
    { headers: { 'Authorization': `Bearer ${token}` } }
9
  );
10
  const data = await response.json();
11
  
12
  // Process payouts
13
  data.payouts.forEach(payout => {
14
    // Handle payout
15
  });
16
  
17
  // Check if more pages exist
18
  hasMore = offset + limit < data.total;
19
  offset += limit;
20
}

Note: The total field indicates the total number of payouts matching your filters. Use this to determine if more pages exist.

Best Practices

• Regularly check payout status to ensure timely delivery
• Monitor failed payouts and investigate failureReason fields
• Use date range filters (startDate and endDate) to review specific time periods (use ISO 8601 format with UTC timezone)
• Use status filter to find all failed payouts for investigation
• Use pagination (limit and offset) for large result sets (see Pagination above)
• Store payout IDs for easy reference and tracking
• Use the total field in list responses to understand the full scope of results and determine if more pages exist
• Implement webhooks for real-time status updates (see Webhooks for setup)
• Use UTC timezone for date filters to avoid timezone issues

For detailed API documentation, see the Payouts API Reference.