List Payouts API

Retrieve a paginated list of your payouts with optional filtering by status, currency, and search terms.

Endpoint

GET /api/v1/payouts

Authentication: API Key + Secret required

Request Headers

X-API-Key: sk_live_abc123def456
X-API-Secret: your-secret-here

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number to retrieve
`limit`	number	20	Items per page (max: 100)
`status`	string	-	Filter by status (e.g., `completed`, `failed`)
`currency`	string	-	Filter by currency code (e.g., `USD`)
`search`	string	-	Search by reference ID or beneficiary email
`sort_by`	string	`created_at`	Field to sort by
`sort_order`	string	`DESC`	Sort direction (`ASC` or `DESC`)

Available Status Filters

created - Newly created payouts
queued - Queued for processing
processing - Currently being processed
settling - Funds settling
action_required - Needs attention
completed - Successfully completed
failed - Failed payouts
cancelled - Cancelled payouts
expired - Expired payouts

Response

Success Response

Status Code: 200 OK

Response Headers:

X-Page: 1
X-Per-Page: 20
X-Total-Count: 156
X-Total-Pages: 8

Response Body:

[
  {
    "id": "pyt_xyz789abc",
    "reference_id": "PAY_2024_001",
    "status": "completed",
    "amount": 100.00,
    "currency": "USD",
    "fees": 1.50,
    "total_amount": 101.50,
    "beneficiary": {
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "country": "US"
    },
    "description": "Bonus Payment",
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:35:00Z"
  },
  {
    "id": "pyt_def456ghi",
    "reference_id": "PAY_2024_002",
    "status": "processing",
    "amount": 50.00,
    "currency": "EUR",
    "fees": 0.75,
    "total_amount": 50.75,
    "beneficiary": {
      "email": "jane.smith@example.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "country": "DE"
    },
    "created_at": "2024-01-15T11:00:00Z",
    "submitted_at": "2024-01-15T11:01:00Z"
  }
]

Response Fields

Payout Object

Field	Type	Description
`id`	string	Unique payout identifier
`reference_id`	string	Client reference
`status`	string	Current status
`amount`	number	Payout amount
`currency`	string	Currency code
`fees`	number	Fees charged
`total_amount`	number	Total deducted (amount + fees)
`beneficiary`	object	Beneficiary information
`failure_code`	string	Error code if failed (nullable)
`failure_reason`	string	Error description if failed (nullable)
`description`	string	Payout description (nullable)
`created_at`	string	Creation timestamp
`queued_at`	string	Queued timestamp (nullable)
`submitted_at`	string	Submission timestamp (nullable)
`completed_at`	string	Completion timestamp (nullable)
`failed_at`	string	Failure timestamp (nullable)
`cancelled_at`	string	Cancellation timestamp (nullable)

Pagination Headers

Header	Description
`X-Page`	Current page number
`X-Per-Page`	Items per page
`X-Total-Count`	Total number of payouts
`X-Total-Pages`	Total number of pages

Error Responses

401 Unauthorized

{
  "error": "UnauthorizedAccess",
  "message": "Authentication required"
}

500 Internal Server Error

{
  "error": "InternalServerError",
  "message": "Failed to retrieve payouts"
}

Examples

Basic List Request

curl -X GET "{{host}}/api/v1/payouts?page=1&limit=20" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

Filter by Status

# Get all completed payouts
curl -X GET "{{host}}/api/v1/payouts?status=completed&page=1&limit=50" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Get all failed payouts
curl -X GET "{{host}}/api/v1/payouts?status=failed" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Get payouts requiring action
curl -X GET "{{host}}/api/v1/payouts?status=action_required" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

Filter by Currency

# Get all USD payouts
curl -X GET "{{host}}/api/v1/payouts?currency=USD" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Get all EUR payouts that completed
curl -X GET "{{host}}/api/v1/payouts?currency=EUR&status=completed" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

Search Payouts

# Search by reference ID
curl -X GET "{{host}}/api/v1/payouts?search=PAY_2024" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Search by beneficiary email
curl -X GET "{{host}}/api/v1/payouts?search=john.doe@example.com" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

Pagination Example

Export Payouts to CSV

Use Cases

Reconciliation

Regularly fetch and compare payouts for accounting reconciliation:

Note: The listPayouts function shown earlier extracts pagination from response headers and returns both payouts and pagination.

Monitor Failed Payouts

Best Practices

Use pagination - Always paginate results for large datasets
Filter efficiently - Use status and currency filters to reduce data transfer
Cache results - Cache payout lists for reporting dashboards
Monitor regularly - Set up scheduled jobs to monitor failed/pending payouts
Implement search - Use the search parameter for quick lookups

Create Payout - Create new payouts
Get Payout - Get detailed payout information
Cancel Payout - Cancel pending payouts

List Payouts API

On this page