Initiate a payout from your available transfer balance. You can use an existing beneficiaryId or provide a beneficiary object and Kyshi will find or create the beneficiary during initiation.

-H "x-api-key: your_secret_key"

POST {{host}}/v1/transfer

Request Body

Field	Data Type	Required	Description
beneficiaryId	string	Yes, if `beneficiary` is not supplied	Existing beneficiary ID.
beneficiary	object	Yes, if `beneficiaryId` is not supplied	Beneficiary details using the Create Beneficiary fields.
currency	string	Yes	Payout currency. Supported payout currencies include `NGN`, `GHS`, `KES`, and `XOF`, depending on what is enabled for your business.
amount	number	Yes	Amount to transfer in major currency units.
narration	string	Yes	Transfer narration.

{
  "beneficiaryId": "8495ec4e-ce21-405f-b0cf-982702881f4d",
  "currency": "NGN",
  "amount": 2000,
  "narration": "Supplier payout"
}

{
  "beneficiaryId": "8495ec4e-ce21-405f-b0cf-982702881f4d",
  "currency": "XOF",
  "amount": 5000,
  "narration": "Customer withdrawal"
}

You can also send XOF with an inline beneficiary:

{
  "currency": "XOF",
  "amount": 5000,
  "narration": "Customer withdrawal",
  "beneficiary": {
    "accountName": "Jean Kouadio",
    "accountNumber": "2250700000000",
    "bankName": "ORANGE_CIV",
    "bankCode": "ORANGE_CIV",
    "currency": "XOF",
    "description": "Customer mobile money wallet"
  }
}

{
  "status": true,
  "message": "Success",
  "code": 201,
  "data": {
    "transferCode": "TRF_HzmYr2nf1TIdilc",
    "reference": "KYSHI-1778623597453",
    "fees": {
      "vat": 0,
      "fee": 5,
      "processorFee": 10,
      "allInclusiveKyshiFee": 5,
      "others": {},
      "totalFees": 15,
      "stampDuty": 0
    }
  }
}

Notes

Amounts are in major currency units.
The total amount debited is the transfer amount plus totalFees.
Kyshi returns Insufficient Funds when your available balance cannot cover the transfer amount and fees.
For XOF mobile money payouts, the initial response means Kyshi has submitted the payout. The transaction may be PENDING for a few seconds until the mobile money provider confirms the final status.
Store the returned reference and verify the transaction with GET /v1/transactions/verify/{reference} until the status is SUCCESS or FAILED.