Initiate a remittance payment

This API function is invoked to submit requests for cross-border remittance transactions. Recipients will receive funds into either their mobile money accounts or bank accounts in their respective countries.

The payload varies based on whether the recipient will be receiving money into their mobile money account(cross-border B2C remittance transaction) or bank account(cross-border bank payout remittance).

The recipient object for cross-border bank payout remittance transaction has extra fields:

  • destinationBankCode- The unique identifier code for the destination bank where funds will be disbursed.

Example: 000201

  • destinationBankName- The official name of the destination bank.

Example: GTBank plc

  • destinationAccountName- The full name of the account holder receiving the funds.

Example: John Doe

  • destinationAccountNo- The account number for the recipient’s account.

Example: 01234567890

Request Payload

{
  "countryCode": "KE",
  "serviceCode": "KE-MPESA-REMITTANCE",
  "payerTransactionID": "{{$guid}}",
  "narration": "Remittance B2C payout",
  "MSISDN": "8433606258",
  "paymentDate": "2023-03-24 15:43:29",
  "credentials": {
    "username": "sandboxUser",
    "password": "sandboxPassword!"
  },
  "remitter": {
    "fullName": "Dorothy AKees",
    "email": "[email protected]",
    "address": "3068 KesslaWay Street",
    "phoneNumber": "8433606258",
    "idType": "SocialSecurityNumber",
    "idNumber": "657-18-9292",
    "idIssuePlace": "Nairobi",
    "idIssueDate": "1997/01/03",
    "idExpireDate": "1997/01/03",
    "nationality": "Kenyan",
    "dateOfBirth": "1997/01/03",
    "country": "US",
    "financialInstitution": "FooCreditUnion",
    "sourceOfFunds": "Business",
    "principalActivity": "Business",
    "state": "california",
    "city": "Nairobi",
    "postalCode": "00100",
    "zipCode": "18291",
    "relationshipWithRecipient": "sister"
  },
  "recipient": {
    "fullName": "John Doe",
    "phoneNumber": "254782694441"
  },
  "transactionDetails": {
    "sourceCurrency": "USD",
    "destinationCurrency": "KES",
    "conversionRate": "0.08882",
    "localCurrencyAmount": 14000.00,
    "foreignCurrencyAmount": 100,
    "purposeOfRemittance": "monthly allowance",
    "sourceCountryCode": "US",
    "destinationCountryCode": "KE"
  },
  "extraData": {
    "callbackUrl": ""
  }
}
{
  "countryCode": "KE",
  "serviceCode": "KE-BANK-PAYOUT-REMITTANCE",
  "payerTransactionID": "{{$guid}}",
  "narration": "Remittance bank payout",
  "MSISDN": "8433606258",
  "paymentDate": "2023-03-24 15:43:29",
  "credentials": {
    "username": "sandboxUser",
    "password": "sandboxPassword!"
  },
  "remitter": {
    "fullName": "Dorothy AKees",
    "email": "[email protected]",
    "address": "3068KesslaWay",
    "phoneNumber": "8433606258",
    "idType": "SocialSecurityNumber",
    "idNumber": "657-18-9292",
    "idIssuePlace": "Nairobi",
    "idIssueDate": "19970103",
    "idExpireDate": "19970103",
    "nationality": "Kenyan",
    "dateOfBirth": "19970103",
    "country": "US",
    "financialInstitution": "FooCreditUnion",
    "sourceOfFunds": "Business",
    "principalActivity": "Business",
    "state": "california",
    "city": "Nairobi",
    "postalCode": "00100",
    "zipCode": "18291",
    "relationshipWithRecipient": "sister"
  },
  "recipient": {
    "fullName": "John Doe",
    "destinationAccountName": "John Doe",
    "destinationAccountNo": "0122000000",
    "destinationBank": "KCBBank",
    "destinationBankCode": "11011",
    "phoneNumber": "254782694441"
  },
  "transactionDetails": {
    "sourceCurrency": "USD",
    "destinationCurrency": "KES",
    "conversionRate": "0.08882",
    "localCurrencyAmount": 14000.00,
    "foreignCurrencyAmount": 100,
    "purposeOfRemittance": "monthly allowance",
    "sourceCountryCode": "US",
    "destinationCountryCode": "KE"
  },
  "extraData": {
    "callbackUrl": ""
  }
}
ParameterTypeDescriptionRequired
countryCodeStringCountry ISO code.Yes
serviceCodeStringCode of the service being consumedYes
payerTransactionIDStringMerchant unique identifierYes
narrationStringDescriptionNo
MSISDNStringSender's phone numberYes
credentialsObject
credentials.usernameMerchant's usernameYes
credentials.passwordMerchant's passwordYes
remitterObject
remitter.fullNameStringSender's nameYes
remitter.emailStringSender's email addressNo
remitter.addressStringPermanent address of the sender
NB : Should be 64 characters, extra characters will be truncated during processing
Yes
remitter.phoneNumberStringSender's phone numberYes
remitter.idTypeStringSender's Identification e.g. Passport,NationalIDNo
remitter.idNumberStringSender's Identification numberNo
remitter.idIssuePlaceStringSender's Identification place of issueNo
remitter.idIssueDateStringSender's Identification date of issue format yyyy/MM/dd Example: 1997/01/03No
remitter.idExpireDateStringSender's Identification expiry date format yyyy/MM/dd. Example: 1997/01/03No
remitter.nationalityStringSender's country of origin as indicated on their Identification document e.g KenyanYes
remitter.dateOfBirthStringDate of birth in format yyyy/MM/dd . Example: 1997/01/03No
remitter.countryStringSender's country of residence. Example: USYes
remitter.financialInstitutionStringSender's financial institutionYes
remitter.sourceOfFundsStringSender's source of fundsYes
remitter.principalActivityStringSender's principal activityNo
remitter.stateStringSender's stateNo
remitter.cityStringSender's cityNo
remitter.postalCodeStringSender's postal codeNo
remitter.zipCodeStringSender's zip codeNo
remitter.relationshipWithRecipientStringSender's relationship with the recipientNo
recipientObject
recipient.fullNameStringRecipient's full nameYes
recipient.emailAddressStringRecipient's email addressNo
recipient.addressStringRecipient's addressNo
recipient.destinationAccountNameStringRecipient's destination account nameNo
recipient.destinationAccountNumberStringRecipient's account numberNo
recipient.phoneNumberStringRecipient's phone number in format 2547xxxxxxxxYes
recipient.idTypeStringRecipient's identification typeNo
recipient.idNumberStringRecipient's identification numberNo
recipient.destinationBankStringRecipient's financial institution e.g. KCB BankNo
recipient.destinationBankCodeStringRecipient's Institution IdentifierNo
recipient.institutionBranchStringRecipient's Institution branch e.g. NakuruNo
recipient.countryCodeStringRecipient's country code e.g. KENo
recipient.nationalityStringRecipient's nationalityNo
transactionDetailsObject
transactionDetails.sourceCurrencyStringTransaction source currency e.g. USDYes
transactionDetails.destinationCurrencyStringTransaction destination currency e.g. KESYes
transactionDetails.conversionRateDoubleTransaction conversion rateYes
transactionDetails.localCurrencyAmountDoubleTransaction amount in local currencyYes
transactionDetails.foreignCurrencyAmountDoubleTransaction amount in foreign currencyYes
transactionDetails.purposeOfRemittanceStringPurpose of money transferYes
transactionDetails.sourceCountryCodeStringSource country code e.g. USYes
transactionDetails.destinationCountryCodeStringDestinations country code e.g. KEYes
extraDataObject

Response

{
    "authStatus": {
        "authStatusCode": 131,
        "authStatusDescription": "Authentication was successful"
    },
    "results": [
        {
            "statusCode": 139,
            "statusDescription": "Payment pending acknowledgement",
            "payerTransactionID": "yourUniqueID",
            "beepTransactionID": 10324841472
        }
    ]
}

Remittance Status Codes

statusCodestatusDescription
104Generic exception occurred with matching appropriate description
106Inactive service
109Customer MSISDN missing
110Invalid Customer MSISDN
111Invalid invoice amount
115Invalid currency code specified
120Account number not specified
139Payment posted successfully and pending acknowledgement.
146Invoice does not exist
167Invalid serviceID
174Generic failure occurred with appropriate status description
229Duplicate payment found
230Insufficient Float Balance
231Amount specified is greater than maximum allowed for service
232Amount specified is less than minimum allowed for service
Language
Click Try It! to start a request and see the response here!