Initiate a remittance payment

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": ""
  }
}

Parameter	Type	Description	Required
countryCode	String	Country ISO code.	Yes
serviceCode	String	Code of the service being consumed	Yes
payerTransactionID	String	Merchant unique identifier	Yes
narration	String	Description	No
MSISDN	String	Sender's phone number	Yes
credentials	Object
credentials.username		Merchant's username	Yes
credentials.password		Merchant's password	Yes
remitter	Object
remitter.fullName	String	Sender's name	Yes
remitter.email	String	Sender's email address	No
remitter.address	String	Permanent address of the sender NB : Should be 64 characters, extra characters will be truncated during processing	Yes
remitter.phoneNumber	String	Sender's phone number	Yes
remitter.idType	String	Sender's Identification e.g. Passport,NationalID	No
remitter.idNumber	String	Sender's Identification number	No
remitter.idIssuePlace	String	Sender's Identification place of issue	No
remitter.idIssueDate	String	Sender's Identification date of issue format yyyy/MM/dd Example: `1997/01/03`	No
remitter.idExpireDate	String	Sender's Identification expiry date format yyyy/MM/dd. Example: `1997/01/03`	No
remitter.nationality	String	Sender's country of origin as indicated on their Identification document e.g Kenyan	Yes
remitter.dateOfBirth	String	Date of birth in format yyyy/MM/dd . Example: `1997/01/03`	No
remitter.country	String	Sender's country of residence. Example: `US`	Yes
remitter.financialInstitution	String	Sender's financial institution	Yes
remitter.sourceOfFunds	String	Sender's source of funds	Yes
remitter.principalActivity	String	Sender's principal activity	No
remitter.state	String	Sender's state	No
remitter.city	String	Sender's city	No
remitter.postalCode	String	Sender's postal code	No
remitter.zipCode	String	Sender's zip code	No
remitter.relationshipWithRecipient	String	Sender's relationship with the recipient	No
recipient	Object
recipient.fullName	String	Recipient's full name	Yes
recipient.emailAddress	String	Recipient's email address	No
recipient.address	String	Recipient's address	No
recipient.destinationAccountName	String	Recipient's destination account name	No
recipient.destinationAccountNumber	String	Recipient's account number	No
recipient.phoneNumber	String	Recipient's phone number in format 2547xxxxxxxx	Yes
recipient.idType	String	Recipient's identification type	No
recipient.idNumber	String	Recipient's identification number	No
recipient.destinationBank	String	Recipient's financial institution e.g. KCB Bank	No
recipient.destinationBankCode	String	Recipient's Institution Identifier	No
recipient.institutionBranch	String	Recipient's Institution branch e.g. Nakuru	No
recipient.countryCode	String	Recipient's country code e.g. KE	No
recipient.nationality	String	Recipient's nationality	No
transactionDetails	Object
transactionDetails.sourceCurrency	String	Transaction source currency e.g. USD	Yes
transactionDetails.destinationCurrency	String	Transaction destination currency e.g. KES	Yes
transactionDetails.conversionRate	Double	Transaction conversion rate	Yes
transactionDetails.localCurrencyAmount	Double	Transaction amount in local currency	Yes
transactionDetails.foreignCurrencyAmount	Double	Transaction amount in foreign currency	Yes
transactionDetails.purposeOfRemittance	String	Purpose of money transfer	Yes
transactionDetails.sourceCountryCode	String	Source country code e.g. US	Yes
transactionDetails.destinationCountryCode	String	Destinations country code e.g. KE	Yes
extraData	Object

Response

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

Remittance Status Codes

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