List Payouts

Fetch payouts

curl --request GET \
  --url https://gateway.useyala.com/api/public/payouts \
  --header 'x-api-key: <api-key>'

{
  "statusCode": 200,
  "message": "success",
  "data": [
    {
      "id": "ff412724-cd9b-4bd5-91c9-8ba7c1662e5c",
      "payoutRef": "88WWRnkRWu",
      "baseAmount": "1000.00",
      "baseCurrency": "USD",
      "amountToBeSent": "0.65",
      "currencyToBeSent": "NGN",
      "status": "PENDING_APPROVAL",
      "businessId": "b9130e5b-8804-451b-9ecf-65660e3a36b7",
      "supportingDocument": "https://sample.com/doc",
      "transactionDate": null,
      "method": "NIP",
      "channel": null,
      "transactionFees": "0.07",
      "methodFees": "0.00",
      "VAT": "0.00",
      "meta": {
        "statusChange": [
          {
            "updatedBy": "API ",
            "email": "API",
            "status": "PENDING_APPROVAL",
            "date": "2025-01-16T12:57:49.996Z"
          }
        ],
        "exchangeRate": {
          "from": "NGN",
          "to": "USD",
          "id": "a836fb63-a11b-4952-896d-7ef7e01fea14",
          "sellRate": 1677.808472,
          "sellSpread": 0.75,
          "buyRate": 1648.54248,
          "buySpread": -0.75,
          "marketRate": 1661,
          "code": "USD/NGN"
        },
        "fee": {
          "amount": 0.06646100000000388,
          "currency": "USD",
          "feeBearer": "TENANT"
        }
      },
      "narration": "Andromeda Galaxy",
      "riskLevel": "LOW",
      "source": "WEB_APP",
      "createdAt": "2025-10-20T19:38:51.230Z",
      "updatedAt": "2025-11-30T13:49:21.769Z",
      "deletedAt": null,
      "beneficiary": {
        "countryCode": "NGA",
        "bankCountryCode": "NGA",
        "accountNumber": "8068487823",
        "accountName": "Will Wonker",
        "bankName": "OPay",
        "accountCurrency": "NGN",
        "payoutMethod": "SWIFT",
        "isIndividual": true,
        "address": "2, 4th Avenue, Off Prince Ademola Eletu way, Jakande, Lekki",
        "city": "Lekki",
        "postCode": "SG1 5LH",
        "swiftNumber": "34323232",
        "routingNumber": "",
        "sortCode": "111111",
        "phoneNumber": "",
        "email": "",
        "bankBranchCode": "",
        "bankAddress": "",
        "bankCode": "34323232",
        "bicNumber": "34323232",
        "riskLevel": "LOW",
        "verificationStatus": "PENDING",
        "id": "2b838df3-47bf-4961-a9fc-dd94c5fa9e47",
        "isWatchListed": false,
        "country": {
          "id": "0d75ba90-1392-4442-81b6-5fc76c32d19b",
          "name": "Nigeria",
          "code": "NGA",
          "currencyCode": "NGN",
          "score": 0,
          "payoutCurrencies": [
            {
              "code": "USD",
              "name": "Dollars"
            }
          ],
          "tradingStartTime": "00:00:00",
          "tradingEndTime": "23:00:00",
          "timeZone": 1,
          "cpi": 0,
          "gdpPerCapitaInUsd": 0,
          "globalRating": "B-",
          "isProhibited": false,
          "henleyPassportIndex": 45,
          "createdAt": "2024-05-12T16:42:58.176Z",
          "updatedAt": "2025-05-21T15:26:56.000Z",
          "deletedAt": null
        },
        "bankCountry": {
          "id": "0d75ba90-1392-4442-81b6-5fc76c32d19b",
          "name": "Nigeria",
          "code": "NGA",
          "currencyCode": "NGN",
          "score": 0,
          "payoutCurrencies": [
            {
              "code": "USD",
              "name": "Dollars"
            }
          ],
          "tradingStartTime": "00:00:00",
          "tradingEndTime": "23:00:00",
          "timeZone": 1,
          "cpi": 0,
          "gdpPerCapitaInUsd": 0,
          "globalRating": "B-",
          "isProhibited": false,
          "henleyPassportIndex": 45,
          "createdAt": "2024-05-12T16:42:58.176Z",
          "updatedAt": "2025-05-21T15:26:56.000Z",
          "deletedAt": null
        }
      }
    }
  ],
  "meta": {
    "total": 199,
    "page": 1,
    "limit": 10,
    "size": 5
  }
}

GET

payouts

Fetch payouts

curl --request GET \
  --url https://gateway.useyala.com/api/public/payouts \
  --header 'x-api-key: <api-key>'

{
  "statusCode": 200,
  "message": "success",
  "data": [
    {
      "id": "ff412724-cd9b-4bd5-91c9-8ba7c1662e5c",
      "payoutRef": "88WWRnkRWu",
      "baseAmount": "1000.00",
      "baseCurrency": "USD",
      "amountToBeSent": "0.65",
      "currencyToBeSent": "NGN",
      "status": "PENDING_APPROVAL",
      "businessId": "b9130e5b-8804-451b-9ecf-65660e3a36b7",
      "supportingDocument": "https://sample.com/doc",
      "transactionDate": null,
      "method": "NIP",
      "channel": null,
      "transactionFees": "0.07",
      "methodFees": "0.00",
      "VAT": "0.00",
      "meta": {
        "statusChange": [
          {
            "updatedBy": "API ",
            "email": "API",
            "status": "PENDING_APPROVAL",
            "date": "2025-01-16T12:57:49.996Z"
          }
        ],
        "exchangeRate": {
          "from": "NGN",
          "to": "USD",
          "id": "a836fb63-a11b-4952-896d-7ef7e01fea14",
          "sellRate": 1677.808472,
          "sellSpread": 0.75,
          "buyRate": 1648.54248,
          "buySpread": -0.75,
          "marketRate": 1661,
          "code": "USD/NGN"
        },
        "fee": {
          "amount": 0.06646100000000388,
          "currency": "USD",
          "feeBearer": "TENANT"
        }
      },
      "narration": "Andromeda Galaxy",
      "riskLevel": "LOW",
      "source": "WEB_APP",
      "createdAt": "2025-10-20T19:38:51.230Z",
      "updatedAt": "2025-11-30T13:49:21.769Z",
      "deletedAt": null,
      "beneficiary": {
        "countryCode": "NGA",
        "bankCountryCode": "NGA",
        "accountNumber": "8068487823",
        "accountName": "Will Wonker",
        "bankName": "OPay",
        "accountCurrency": "NGN",
        "payoutMethod": "SWIFT",
        "isIndividual": true,
        "address": "2, 4th Avenue, Off Prince Ademola Eletu way, Jakande, Lekki",
        "city": "Lekki",
        "postCode": "SG1 5LH",
        "swiftNumber": "34323232",
        "routingNumber": "",
        "sortCode": "111111",
        "phoneNumber": "",
        "email": "",
        "bankBranchCode": "",
        "bankAddress": "",
        "bankCode": "34323232",
        "bicNumber": "34323232",
        "riskLevel": "LOW",
        "verificationStatus": "PENDING",
        "id": "2b838df3-47bf-4961-a9fc-dd94c5fa9e47",
        "isWatchListed": false,
        "country": {
          "id": "0d75ba90-1392-4442-81b6-5fc76c32d19b",
          "name": "Nigeria",
          "code": "NGA",
          "currencyCode": "NGN",
          "score": 0,
          "payoutCurrencies": [
            {
              "code": "USD",
              "name": "Dollars"
            }
          ],
          "tradingStartTime": "00:00:00",
          "tradingEndTime": "23:00:00",
          "timeZone": 1,
          "cpi": 0,
          "gdpPerCapitaInUsd": 0,
          "globalRating": "B-",
          "isProhibited": false,
          "henleyPassportIndex": 45,
          "createdAt": "2024-05-12T16:42:58.176Z",
          "updatedAt": "2025-05-21T15:26:56.000Z",
          "deletedAt": null
        },
        "bankCountry": {
          "id": "0d75ba90-1392-4442-81b6-5fc76c32d19b",
          "name": "Nigeria",
          "code": "NGA",
          "currencyCode": "NGN",
          "score": 0,
          "payoutCurrencies": [
            {
              "code": "USD",
              "name": "Dollars"
            }
          ],
          "tradingStartTime": "00:00:00",
          "tradingEndTime": "23:00:00",
          "timeZone": 1,
          "cpi": 0,
          "gdpPerCapitaInUsd": 0,
          "globalRating": "B-",
          "isProhibited": false,
          "henleyPassportIndex": 45,
          "createdAt": "2024-05-12T16:42:58.176Z",
          "updatedAt": "2025-05-21T15:26:56.000Z",
          "deletedAt": null
        }
      }
    }
  ],
  "meta": {
    "total": 199,
    "page": 1,
    "limit": 10,
    "size": 5
  }
}

Overview

Fetch a paginated list of payouts for your business. Use query parameters to filter by payout reference, status, or other criteria.

Query Parameters

Parameter	Type	Required	Description
`filter[payoutRef]`	string	No	Filter by payout reference (e.g., `88WWRnkRW`)

Usage Notes

Returns paginated results with metadata including total count, current page, and limit.
Use the payoutRef filter to find a specific payout by its unique reference.
Each payout includes beneficiary details, status, fees, and transaction metadata.
The meta.statusChange array provides a timeline of status updates for each payout.

Store payoutRef values when creating payouts so you can easily query them later for status updates or reconciliation.

Authorizations

x-api-key

string

header

required

Query Parameters

filter[payoutRef]

string

Filter payouts by payout reference

Example:

"88WWRnkRW"

Response

A successful response

statusCode

integer

Example:

200

message

string

Example:

"success"

data

object[]

Show child attributes

data.id

string<uuid>

Example:

"ff412724-cd9b-4bd5-91c9-8ba7c1662e5c"

data.payoutRef

string

Example:

"88WWRnkRWu"

data.baseAmount

string

Example:

"1000.00"

data.baseCurrency

string

Example:

"USD"

data.amountToBeSent

string

Example:

"0.65"

data.currencyToBeSent

string

Example:

"NGN"

data.status

string

Example:

"PENDING_APPROVAL"

data.businessId

string<uuid>

Example:

"b9130e5b-8804-451b-9ecf-65660e3a36b7"

data.supportingDocument

string<uri>

Example:

"https://sample.com/doc"

data.transactionDate

string<date-time> | null

Example:

null

data.method

string

Example:

"NIP"

data.channel

string | null

Example:

null

data.transactionFees

string

Example:

"0.07"

data.methodFees

string

Example:

"0.00"

data.VAT

string

Example:

"0.00"

data.meta

object

Show child attributes

data.meta.statusChange

object[]

Show child attributes

data.meta.statusChange.updatedBy

string

Example:

"API "

data.meta.statusChange.email

string

Example:

"API"

data.meta.statusChange.status

string

Example:

"PENDING_APPROVAL"

data.meta.statusChange.date

string<date-time>

Example:

"2025-01-16T12:57:49.996Z"

data.meta.exchangeRate

object

Show child attributes

data.meta.exchangeRate.from

string

Example:

"NGN"

data.meta.exchangeRate.to

string

Example:

"USD"

data.meta.exchangeRate.id

string<uuid>

Example:

"a836fb63-a11b-4952-896d-7ef7e01fea14"

data.meta.exchangeRate.sellRate

number<float>

Example:

1677.808472

data.meta.exchangeRate.sellSpread

number<float>

Example:

0.75

data.meta.exchangeRate.buyRate

number<float>

Example:

1648.54248

data.meta.exchangeRate.buySpread

number<float>

Example:

-0.75

data.meta.exchangeRate.marketRate

number<float>

Example:

1661

data.meta.exchangeRate.code

string

Example:

"USD/NGN"

data.meta.fee

object

Show child attributes

data.meta.fee.amount

number

Example:

0.06646100000000388

data.meta.fee.currency

string

Example:

"USD"

data.meta.fee.feeBearer

string

Example:

"TENANT"

data.narration

string

Example:

"Andromeda Galaxy"

data.riskLevel

string

Example:

"LOW"

data.source

string

Example:

"WEB_APP"

data.createdAt

string<date-time>

Example:

"2025-10-20T19:38:51.230Z"

data.updatedAt

string<date-time>

Example:

"2025-11-30T13:49:21.769Z"

data.deletedAt

string<date-time> | null

Example:

null

data.beneficiary

object

Show child attributes

data.beneficiary.countryCode

string

required

Country code of beneficiary

Example:

"NGA"

data.beneficiary.bankCountryCode

string

required

Country code of beneficiary's bank

Example:

"NGA"

data.beneficiary.accountNumber

string

required

Beneficiary's account number

Example:

"8068487823"

data.beneficiary.accountName

string

required

Beneficiary's account name

Example:

"Will Wonker"

data.beneficiary.bankName

string

required

Name of beneficiary's bank

Example:

"OPay"

data.beneficiary.accountCurrency

string

required

Currency of beneficiary's account

Example:

"NGN"

data.beneficiary.payoutMethod

enum<string>

required

Payment method for this beneficiary

Available options:

SWIFT,

NIP,

HK_FPS,

CHINA_WIRE,

FASTER_PAYMENTS,

WIRE,

ACH,

SEPA

Example:

"SWIFT"

data.beneficiary.isIndividual

boolean

required

Whether beneficiary is an individual (true) or business (false)

Example:

true

data.beneficiary.address

string

Beneficiary's address

Example:

"2, 4th Avenue, Off Prince Ademola Eletu way, Jakande, Lekki"

data.beneficiary.city

string

Beneficiary's city

Example:

"Lekki"

data.beneficiary.postCode

string

Beneficiary's postal code

Example:

"SG1 5LH"

data.beneficiary.swiftNumber

string

SWIFT/BIC code

Example:

"34323232"

data.beneficiary.routingNumber

string

Routing number (for US banks)

Example:

""

data.beneficiary.sortCode

string

Sort code (for UK banks)

Example:

"111111"

data.beneficiary.phoneNumber

string

Beneficiary's phone number

Example:

""

data.beneficiary.email

string<email>

Beneficiary's email address

Example:

""

data.beneficiary.bankBranchCode

string

Bank branch code

Example:

""

data.beneficiary.bankAddress

string

Bank address

Example:

""

data.beneficiary.bankCode

string

Bank code

Example:

"34323232"

data.beneficiary.bicNumber

string

BIC number

Example:

"34323232"

data.beneficiary.riskLevel

string

Example:

"LOW"

data.beneficiary.verificationStatus

string

Example:

"PENDING"

data.beneficiary.id

string<uuid>

Example:

"2b838df3-47bf-4961-a9fc-dd94c5fa9e47"

data.beneficiary.isWatchListed

boolean

Example:

false

data.beneficiary.country

object

Show child attributes

data.beneficiary.country.id

string<uuid>

Example:

"0d75ba90-1392-4442-81b6-5fc76c32d19b"

data.beneficiary.country.name

string

Example:

"Nigeria"

data.beneficiary.country.code

string

Example:

"NGA"

data.beneficiary.country.currencyCode

string

Example:

"NGN"

data.beneficiary.country.score

integer

Example:

0

data.beneficiary.country.payoutCurrencies

object[] | null

Show child attributes

data.beneficiary.country.payoutCurrencies.code

string

Example:

"USD"

data.beneficiary.country.payoutCurrencies.name

string

Example:

"Dollars"

data.beneficiary.country.tradingStartTime

string | null

Example:

"00:00:00"

data.beneficiary.country.tradingEndTime

string | null

Example:

"23:00:00"

data.beneficiary.country.timeZone

integer | null

Example:

1

data.beneficiary.country.cpi

number

Example:

0

data.beneficiary.country.gdpPerCapitaInUsd

number

Example:

0

data.beneficiary.country.globalRating

string

Example:

"B-"

data.beneficiary.country.isProhibited

boolean

Example:

false

data.beneficiary.country.henleyPassportIndex

integer

Example:

45

data.beneficiary.country.createdAt

string<date-time>

Example:

"2024-05-12T16:42:58.176Z"

data.beneficiary.country.updatedAt

string<date-time>

Example:

"2025-05-21T15:26:56.000Z"

data.beneficiary.country.deletedAt

string<date-time> | null

Example:

null

data.beneficiary.bankCountry

object

Show child attributes

data.beneficiary.bankCountry.id

string<uuid>

Example:

"0d75ba90-1392-4442-81b6-5fc76c32d19b"

data.beneficiary.bankCountry.name

string

Example:

"Nigeria"

data.beneficiary.bankCountry.code

string

Example:

"NGA"

data.beneficiary.bankCountry.currencyCode

string

Example:

"NGN"

data.beneficiary.bankCountry.score

integer

Example:

0

data.beneficiary.bankCountry.payoutCurrencies

object[] | null

Show child attributes

data.beneficiary.bankCountry.payoutCurrencies.code

string

Example:

"USD"

data.beneficiary.bankCountry.payoutCurrencies.name

string

Example:

"Dollars"

data.beneficiary.bankCountry.tradingStartTime

string | null

Example:

"00:00:00"

data.beneficiary.bankCountry.tradingEndTime

string | null

Example:

"23:00:00"

data.beneficiary.bankCountry.timeZone

integer | null

Example:

1

data.beneficiary.bankCountry.cpi

number

Example:

0

data.beneficiary.bankCountry.gdpPerCapitaInUsd

number

Example:

0

data.beneficiary.bankCountry.globalRating

string

Example:

"B-"

data.beneficiary.bankCountry.isProhibited

boolean

Example:

false

data.beneficiary.bankCountry.henleyPassportIndex

integer

Example:

45

data.beneficiary.bankCountry.createdAt

string<date-time>

Example:

"2024-05-12T16:42:58.176Z"

data.beneficiary.bankCountry.updatedAt

string<date-time>

Example:

"2025-05-21T15:26:56.000Z"

data.beneficiary.bankCountry.deletedAt

string<date-time> | null

Example:

null

Overview

Countries

Payouts

Transactions

Overview

Query Parameters

Usage Notes

Authorizations

Query Parameters

Response

Overview

Countries

Payouts

Transactions

​Overview

​Query Parameters

​Usage Notes

Authorizations

Query Parameters

Response

Overview

Query Parameters

Usage Notes