Get Payout by ID - Yala Payout APIs

Overview

Retrieve payout status and details by ID for the authenticated business. Returns 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 payout reference
`sourceAmount`	number	Amount debited from source wallet
`sourceCurrency`	string	Source currency
`destinationAmount`	number	Amount sent to beneficiary
`destinationCurrency`	string	Destination currency
`status`	string	One of: `PENDING`, `ADDITIONAL_INFO_REQUIRED`, `PROCESSING`, `SUCCESSFUL`, `FAILED`, `REJECTED`. Same values as webhooks.
`statusDetail`	string (optional)	Present when `status` is `PENDING` and submitted additional information is under review. Value: `ADDITIONAL_INFO_UNDER_REVIEW`.
`informationRequests`	array (optional)	Present when `status` is `ADDITIONAL_INFO_REQUIRED`. Each item describes what compliance has requested. See below.
`method`	string	Payment method used
`transactionFees`	number	Transaction fees
`exchangeRate`	number	Exchange rate used for conversion
`createdAt`	string (ISO 8601)	Payout creation timestamp
`updatedAt`	string (ISO 8601)	Last update timestamp
`supportingDocuments`	array	Attached supporting documents (from initiation or PATCH `/documents`). Each item has `id`, `url`, and `uploadedAt`.

informationRequests

Included when status is ADDITIONAL_INFO_REQUIRED. Use this to show your users what to provide. Upload supporting documents with PATCH /documents when a FILE request applies.

Field	Type	Description
`title`	string	Short label for the requested item (e.g. “Invoice copy”).
`description`	string (optional)	Instructions from compliance.
`type`	string	Expected input: `TEXT`, `SELECT`, or `FILE`. For API partners, `FILE` requests are usually resolved by uploading via PATCH `/documents`.
`section`	string (optional)	Grouping label when provided.
`options`	array (optional)	Allowed values when `type` is `SELECT`.
`rejectionReason`	string (optional)	Present when a previous submission was rejected and must be resubmitted.

Error Responses

404 Not Found

{
  "statusCode": 404,
  "message": "Payout not found or not associated with your business",
  "error": "PAYOUT_NOT_FOUND"
}

Solution: Verify the payout ID and ensure it belongs to your business.

401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized"
}

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();
console.log(`Status: ${payout.status}, Amount: ${payout.destinationAmount} ${payout.destinationCurrency}`);

Use this endpoint to check payout status after creation or to display payout details in your dashboard. Alternatively, subscribe to webhook notifications to receive real-time status updates.

Webhooks

Instead of polling this endpoint, you can subscribe to webhook notifications for real-time status updates:

Activate webhooks in your Yala dashboard
Configure your webhook endpoint URL
Receive notifications when payout status changes

The webhook payload includes the payout id (matching the id field in this response) so you can identify which payout was updated.

​Overview

​Request

​Path Parameters

​Headers

​Response

​Response Fields

​informationRequests

​Error Responses

​404 Not Found

​401 Unauthorized

​Usage Example

​Webhooks

Overview

Request

Path Parameters

Headers

Response

Response Fields

informationRequests

Error Responses

404 Not Found

401 Unauthorized

Usage Example

Webhooks