Skip to main content
POST
/
payouts
/
initiate
Initiate a payout transaction
curl --request POST \
  --url https://gateway.useyala.com/api/public/payouts/initiate \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "businessId": "6fd2b69f-c529-4fe4-b680-29256f860553",
  "sourceAmount": 1000,
  "sourceCurrency": "USD",
  "destinationCurrency": "NGN",
  "feeBearer": "TENANT",
  "method": "NIP",
  "destinationCountryCode": "NGA",
  "narration": "Andromeda Galaxy",
  "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"
  },
  "supportingDocument": "https://sample.com/doc"
}
'
{
  "statusCode": 201,
  "message": "success",
  "data": {
    "businessId": "02730067-e309-4e43-b865-ad1e7373fd8f",
    "baseAmount": 3300000,
    "baseCurrency": "NGN",
    "amountToBeSent": 1966.85,
    "currencyToBeSent": "USD",
    "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"
    },
    "supportingDocument": "https://sample.com/doc",
    "method": "SWIFT",
    "narration": "Andromeda Galaxy",
    "VAT": null,
    "methodFees": null,
    "transactionFees": null,
    "beneficiaryId": "a51cc961-366a-4346-be7c-de8541431d3f",
    "status": "PENDING_APPROVAL",
    "business": {
      "id": "02730067-e309-4e43-b865-ad1e7373fd8f",
      "name": "Big O Express",
      "email": "[email protected]",
      "website": "www.bigoexpress.com"
    },
    "riskLevel": "LOW",
    "payoutRef": "1r4Wx1MQEP",
    "category": {},
    "sourceWallet": {
      "id": "b7e5ac80-829f-4b97-b845-1b9a70f9f4ff",
      "type": "BUSINESS_WALLET",
      "balance": 66323010.160000004,
      "currency": "NGN",
      "processor": "Yala",
      "walletRef": "YALA75910",
      "accountNumber": "9252038588",
      "accountName": null
    },
    "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"
      }
    },
    "transactionDate": null,
    "channel": null,
    "id": "7501f00c-7977-4fed-aef7-6b0746bfddc6",
    "createdAt": "2025-01-16T12:57:49.996Z",
    "updatedAt": "2025-01-16T12:57:49.000Z",
    "deletedAt": null,
    "transactions": [
      {
        "amount": -3300000,
        "wallet": {
          "id": "b7e5ac80-829f-4b97-b845-1b9a70f9f4ff"
        },
        "type": "DEBIT",
        "method": "SWIFT",
        "balanceBefore": 69705437.28,
        "balanceAfter": 66405437.28,
        "provider": "YALA",
        "reference": "1r4Wx1MQEP",
        "currency": "NGN",
        "remarks": "Payout",
        "narration": null,
        "code": "TRX_6f4mRvEfDhu16nZHv",
        "meta": null,
        "id": "3620bae6-0cd4-4235-aa4d-cb7a1eef8c00",
        "createdAt": "2025-01-16T12:57:49.982Z",
        "updatedAt": "2025-01-16T12:57:49.982Z"
      }
    ]
  }
}

​
Usage notes

  • Always provide a valid businessId that has sufficient wallet balance in the source currency.
  • Attach supportingDocument links for payouts that require compliance review.
  • The response includes PayoutData with lifecycle fields such as status, riskLevel, and meta.statusChange.
If the payout requires manual approval, it remains in PENDING_APPROVAL until an operator approves it via the Yala dashboard.

Authorizations

​
x-api-key
string
header
required

Body

application/json

Payout initiation request

​
businessId
string<uuid>
required

Unique identifier for the business

Example:

"6fd2b69f-c529-4fe4-b680-29256f860553"

​
sourceAmount
number
required

Amount in the source currency

Example:

1000

​
sourceCurrency
string
required

Source currency code

Example:

"USD"

​
destinationCurrency
string
required

Destination currency code

Example:

"NGN"

​
feeBearer
enum<string>
required

Who bears the fees for this transaction

Available options:
CUSTOMER,
TENANT
Example:

"TENANT"

​
method
enum<string>
required

Payment method

Available options:
SWIFT,
NIP,
HK_FPS,
CHINA_WIRE,
FASTER_PAYMENTS,
WIRE,
ACH,
SEPA
Example:

"NIP"

​
destinationCountryCode
string
required

Destination country code

Example:

"NGA"

​
narration
string
required

Transaction description

Example:

"Andromeda Galaxy"

​
beneficiary
object
required
​
supportingDocument
string<uri>

URL to supporting document

Example:

"https://sample.com/doc"

Response

Payout initiated successfully

​
statusCode
integer

HTTP status code

Example:

201

​
message
string

Response message

Example:

"success"

​
data
object