Skip to main content

Funds Payout

Outbound money transfers from your merchant account to bank accounts or compatible mobile money channels are known as payouts.

This API supports funds payout via a number of methods e.g. Mobile Money, Bank Transfer and many other methods will be supported along the way enabling you to send payments via a simple, secure process that requires only the bank/phone information of the recipients. Please visit this page to learn more about request headers.

Single Transfer - Mobile Money Payout​

curl --location 'https://transfer.dev.mypaygate.co/api/v1/transactions/transfer/single' --header 'x-api-key:  Base_64(MerchantPublicKey)' --header 'Content-Type: application/json' --data-raw '{
"transactionReference": "PYG-TST-SUCC-6271184009",
"country": "Kenya",
"currency": "KES",
"channel": "Mobile Money",
"transactionType": "1",
"beneficiary": {
    "accountName": "John Doe",
    "accountNumber": "254710000000",
    "phoneNumber": "254710000000",
    "accountType": "",
    "identificationType": "",
    "identificationNumber": "",
    "nationalIdNumber": "",
    "bankCode": "KESAF",
    "amount": 250,
    "narration": "Test transaction"
},
"sender": {
    "name": "Test Agent",
    "phoneNumber": "08137271515",
    "email": "daramolatoye@gmail.com",
    "countryCode": "KEN",
    "currencyCode": "KES"
}
}'

Sample Request - Bank Payout​


{
"transactionReference": "PYG-TST-SUCC-\{\{timestampBasedRef\}\}",
"country": "Nigeria",
"currency": "NGN",
"channel": "Bank Transfer",
"transactionType": "1",
"beneficiary": {
  "accountName": "Godwin Abbey",
  "accountNumber": "0000000000",
  "phoneNumber": "254710000000",
  "accountType": "",
  "identificationType": "",
  "identificationNumber": "",
  "nationalIdNumber": "",
  "bankCode": "100004",
  "amount": 100,
  "narration": "Test transaction"
},
"sender": {
  "name": "Godwin Electrical",
  "phoneNumber": "08137179447",
  "email": "bolajivictorawosik@gmail.com",
  "countryCode": "NGA",
  "currencyCode": "NGN"
}
}

Single Transfer - Request Body Parameters​

FieldData TypeDescriptionMandatory
transactionReferenceStringYes
countryStringYes
currencyString-Yes
channelStringThis must be one of these: "Bank Transfer" or "Mobile Money"Yes
transactionTypeStringFor some markets Cameroon - CM; Kenya - KE, it is important to indicate the type of transaction whether it is: 1 (⁠high risk - betting) 2⁠ (⁠low risk - remittance) 3⁠ (crypto)No (Yes, if KES or XAF)
beneficiary.accountNameString-Yes
beneficiary.accountNumberString-Yes
beneficiary.phoneNumberString-No (Yes if request is a low-risk KES payout)
beneficiary.accountTypeStringRequired for South AfricaNo (Yes if ZAF)
beneficiary.identificationTypeStringRequired for South AfricaNo (Yes if ZAF)
beneficiary.identificationNumberStringRequired for South AfricaNo (Yes if ZAF)
beneficiary.nationalIdNumberStringRequired for EgyptNo (Yes if EGP)
beneficiary.bankCodeStringThis can be obtained by calling the Get Banks APIYes
beneficiary.amountDecimal-Yes
beneficiary.narrationString-No
sender.nameString-Yes
sender.phoneNumberString-No (Yes, if XAF)
sender.emailString-Yes
sender.countryCodeString-No (Yes, if KES or XAF)
sender.currencyCodeString-No (Yes, if KES or XAF)

Single Transfer - Sample Response​

{
  "isSuccessful": true,
  "responseCode": "09",
  "responseMessage": "Transaction successfully submitted",
  "responseData": {
      "transactionStatus": "INITIALIZED",
      "merchantReference": "PYG-17050521-1713252829",
      "transactionReference": "PYG-1754037844441048",
      "amount": 1,
      "feeAmount": 50.00
  }
}

Sample Webhooks​

{ 
"data": {
      "transactionStatus": "COMPLETED",
      "merchantReference": "PYG-17050521-TST-SUCC-1752581420",
      "transactionReference": "PYG-1752581428835494",
      "amount": 3,
      "feeAmount": 0.1,
      "valueAmount": 3
      "statusReason": "Successful"
  }
}

Bulk Transfer - Sample Request (POST)​

curl --location 'https://transfer.dev.mypaygate.co/api/v1/transactions/transfer/bulk' --header 'Content-Type: application/json' --header 'x-api-key: {{BASE64(MERCHANT_PUBLIC_KEY)
}}' --data-raw '{
  "transactionReference": "PYG-BCH-17050521-1755771213",
  "currency": "NGN",
  "country": "Nigeria",
  "totalAmount": 1000.0,
  "channel": "Bank Transfer",
  "transactionType": "1",
  "beneficiaries": [
      {
          "accountName": "John Doe",
          "accountNumber": "0000000000",
          "bankCode": "000017",
          "amount": 300.0,
          "narration": "Salary Payment",
          "saveBeneficiary": false,
          "transactionReference": "PYG-TST-SUCC-752c8243-a9ef-4ee6-9231-f9b9f8a735e0"
      },
      {
          "accountName": "Jane Doe",
          "accountNumber": "0000000000",
          "bankCode": "000016",
          "amount": 1200.0,
          "narration": "Salary Payment",
          "saveBeneficiary": false,
          "transactionReference": "PYG-TST-SUCC-c2f0bcff-afff-4443-a063-dbe4338bdf8a"
      },
      {
          "accountName": "Not Doe",
          "accountNumber": "0000000000",
          "bankCode": "000013",
          "amount": 500.0,
          "narration": "Salary Payment",
          "saveBeneficiary": false,
          "transactionReference": "PYG-TST-FAIL-8676594e-5c4b-4503-b907-ee3e3afaed0f"
      }
  ],
  "sender": {
      "name": "Merryweather Securities Inc",
      "phoneNumber": "",
      "email": "adesuyiayo@rocketmail.com"
  }
}'

Bulk Transfer - Request Body Parameters​

FieldData TypeDescriptionMandatory
transactionReferenceStringYes
currencyStringYes
countryStringYes
totalAmountDecimalYes
channelStringYes
beneficiaries.[0].accountNameStringYes
beneficiaries.[0].accountNumberStringYes
beneficiaries.[0].bankCodeStringYes
beneficiaries.[0].amountDecimalYes
beneficiaries.[0].transactionReferenceStringYes
sender.nameStringYes
sender.phoneNumberStringYes
sender.emailStringYes

Bulk Transfer - Sample Response​

{
  "isSuccessful": true,
  "responseCode": "09",
  "responseMessage": "Transactions successfully submitted"
}

Sample Webhooks​

{
"data": {
  "transactionStatus": "COMPLETED",
  "merchantReference": "PYG-TST-SUCC-6347219788",
  "transactionReference": "PG-P-17557806359485D",
  "amount": 250,
  "feeAmount": 5,
  "valueAmount": 250,
  "statusReason": "Successful"
}
}

Base URLs​

note

DEVELOPMENT: - https://transfer.dev.mypaygate.co

PRODUCTION: - https://transfer.prod.mypaygate.co