Retrieve detailed information about a specific payout including status and beneficiary details

Get Payout API

Retrieve detailed information about a specific payout, including its current status and beneficiary details.

Endpoint

GET /api/v1/payouts/:id

Authentication: API Key + Secret required

Request Headers

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

Path Parameters

Parameter	Type	Description
`id`	string	Payout ID (e.g., `pyt_xyz789abc`)

Response

Success Response

Status Code: 200 OK

{
  "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",
    "phone": "+1234567890"
  },
  "description": "Q1 2024 Bonus Payment",
  "created_at": "2024-01-15T10:30:00Z",
  "queued_at": "2024-01-15T10:30:01Z",
  "submitted_at": "2024-01-15T10:31:00Z",
  "completed_at": "2024-01-15T10:35:00Z",
  "failed_at": null,
  "cancelled_at": null
}

Response Fields

Field	Type	Description
`id`	string	Unique payout identifier
`reference_id`	string	Client reference
`status`	string	Current payout status
`amount`	number	Payout amount to beneficiary
`currency`	string	Currency code
`fees`	number	Fees charged
`total_amount`	number	Total deducted from wallet
`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	When queued (nullable)
`submitted_at`	string	When submitted to provider (nullable)
`completed_at`	string	When completed (nullable)
`failed_at`	string	When failed (nullable)
`cancelled_at`	string	When cancelled (nullable)

Failed Payout Response

When a payout has failed, additional failure information is included:

{
  "id": "pyt_failed123",
  "reference_id": "PAY_2024_FAIL",
  "status": "failed",
  "amount": 100.00,
  "currency": "USD",
  "fees": 1.50,
  "total_amount": 101.50,
  "failure_code": "INVALID_ACCOUNT",
  "failure_reason": "The beneficiary account number is invalid or closed",
  "beneficiary": {
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "failed_at": "2024-01-15T10:32:00Z"
}

Common Failure Codes

Code	Description
`INVALID_ACCOUNT`	Beneficiary account is invalid or closed
`INSUFFICIENT_FUNDS`	Provider or wallet insufficient funds
`COMPLIANCE_HOLD`	Transaction held for compliance review
`BENEFICIARY_REJECTED`	Beneficiary rejected the payment
`PROVIDER_ERROR`	Payment provider system error
`EXPIRED`	Payout expired before completion
`LIMIT_EXCEEDED`	Transaction limit exceeded

Error Responses

400 Bad Request - Missing ID

{
  "error": "BadRequest",
  "message": "Payout ID is required"
}

404 Not Found

{
  "error": "NotFound",
  "message": "Payout not found"
}

401 Unauthorized

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

Examples

Basic Request

curl -X GET "{{host}}/api/v1/payouts/pyt_xyz789abc" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

Poll for Status Updates

Track Payout Timeline

Handle Different Statuses

Use Cases

Display Payout Status to End User

Audit Trail for Compliance

Best Practices

Store payout IDs - Always save the payout ID returned from creation for later retrieval
Poll responsibly - Use reasonable intervals (5-10 seconds) when polling for status
Handle all statuses - Implement handling for every possible status
Log timestamps - Store timestamp history for audit and debugging purposes
Parse failure codes - Use failure codes for automated retry decisions

Create Payout - Create new payouts
List Payouts - List all payouts
Cancel Payout - Cancel pending payouts

Get Payout API

On this page