Get Payout by ID - Yala Payout APIs

Overview

Retrieve one payout by ID for the authenticated business. Swaps are not returned here. Use Get Swap by ID for swaps created with Initiate Swap. Pass the id from Initiate Payout or List Payouts. The response includes conversion information, exchange rates, fees, timestamps, attached supporting documents (from creation or added via PATCH /documents), and requested information when compliance needs more from you (ADDITIONAL_INFO_REQUIRED).

Request

GET /v1/payout-api/payouts/{id} HTTP/1.1
Host: gateway.staging.useyala.com
x-api-key: <YOUR_API_KEY>

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	Payout identifier

Headers

Header	Required	Description
`x-api-key`	Yes	Your API key

Response

{
  "id": "payout-id-uuid",
  "payoutRef": "PAY-2024-001",
  "sourceAmount": 10000,
  "sourceCurrency": "NGN",
  "destinationAmount": 42.5,
  "destinationCurrency": "CNY",
  "status": "ADDITIONAL_INFO_REQUIRED",
  "method": "ALIPAY",
  "transactionFees": 0,
  "exchangeRate": 235.0,
  "createdAt": "2024-01-20T10:00:00Z",
  "updatedAt": "2024-01-21T09:00:00Z",
  "informationRequests": [
    {
      "title": "Invoice copy",
      "description": "Please provide a clearer invoice showing beneficiary name",
      "type": "FILE"
    }
  ],
  "supportingDocuments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://example.com/document.pdf",
      "uploadedAt": "2024-01-20T10:00:00Z"
    }
  ]
}

When submitted additional information is under review internally, status is PENDING and statusDetail is ADDITIONAL_INFO_UNDER_REVIEW:

{
  "id": "payout-id-uuid",
  "status": "PENDING",
  "statusDetail": "ADDITIONAL_INFO_UNDER_REVIEW"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Payout identifier
`payoutRef`	string	Human-readable reference
`status`	string	Partner-facing status
`statusDetail`	string (optional)	Present when `status` is `PENDING` and submitted additional information is under review. Value: `ADDITIONAL_INFO_UNDER_REVIEW`.
`method`	string	Payout method (`NIP`, `SWIFT`, `ALIPAY`, etc.). Never `SWAP` on this endpoint.
`sourceAmount`	number	Amount debited from source wallet
`sourceCurrency`	string	Source currency
`destinationAmount`	number	Amount sent to beneficiary
`destinationCurrency`	string	Destination currency
`exchangeRate`	number	Rate used for conversion
`transactionFees`	number	Fee amount
`createdAt`	string (ISO 8601)	Creation time
`updatedAt`	string (ISO 8601)	Last update time
`informationRequests`	array (optional)	Present when status is `ADDITIONAL_INFO_REQUIRED`
`supportingDocuments`	array	Attached documents

Errors

Status	Code	When
404	`PAYOUT_NOT_FOUND`	Unknown id, wrong business, or the id belongs to a swap

Usage Example

const response = await fetch(
  `https://gateway.staging.useyala.com/v1/payout-api/payouts/${payoutId}`,
  { headers: { 'x-api-key': apiKey } },
);
const payout = await response.json();

​Overview

​Request

​Path Parameters

​Headers

​Response

​Response Fields

​Errors

​Usage Example