Get Swap by ID - Yala Payout APIs

Overview

Retrieve one swap by ID for the authenticated business. The record must have method SWAP. For payouts, use Get Payout by ID. Pass the id from Initiate Swap or List Swaps. Swaps do not use supporting documents. transactionFees is 0.

Request

GET /v1/payout-api/payouts/swaps/{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	Swap identifier

Headers

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

Response

{
  "id": "223e4567-e89b-12d3-a456-426614174001",
  "payoutRef": "PAY-2024-002",
  "status": "PROCESSING",
  "method": "SWAP",
  "sourceAmount": 1000,
  "sourceCurrency": "USD",
  "destinationAmount": 1500000,
  "destinationCurrency": "NGN",
  "exchangeRate": 1500,
  "transactionFees": 0,
  "createdAt": "2024-01-21T12:00:00.000Z",
  "updatedAt": "2024-01-21T12:00:00.000Z",
  "supportingDocuments": []
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Swap identifier
`payoutRef`	string	Human-readable reference
`status`	string	Partner-facing status (`PROCESSING` until confirmed or reversed)
`method`	string	Always `SWAP`
`sourceAmount`	number	Amount debited from source wallet
`sourceCurrency`	string	Source wallet currency
`destinationAmount`	number	Amount credited to destination wallet
`destinationCurrency`	string	Destination wallet currency
`exchangeRate`	number	Rate used for the swap
`transactionFees`	number	Always `0` for swaps
`createdAt`	string (ISO 8601)	Creation time
`updatedAt`	string (ISO 8601)	Last update time

Errors

Status	Code	When
404	`SWAP_NOT_FOUND`	Unknown id, wrong business, or the id is a payout (not a swap)

Usage Example

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