post https://api-approval.tingg.africa/v2/remittance/payments/initiate-remittance
This API function is invoked by remittance customers to post requests for cross border remittance transaction(cross-border transaction). The recipient can receive money into mobile money account and bank accounts in the respective countries.
This is Suitable for Mobile Money Payout Transactions B2C, Refunds that are cross border.
The source of funds will be a merchant Float account configured on our Payment Gateway. Therefore, the
MSISDNandaccountNumbercan be similar.
Suitable for bank transfers. Unlike other payloads, bank transfers have a few extra parameters nested in the transactionDetails.
**destinationBankCode**- This is simply the target bank identified by its unique code to which funds will be disbursed. E.g., 000201.
**destinationBankName**- A unique name for the subject bank. E.g., GTBank plc.
**destinationAccountName**- This Should be the account holder's name to where money is being sent, known as the target account. E.g., John Doe
**destinationAccountNo**- This should be the unique account number for the target account receiving the disbursed funds.
Request
{
"countryCode":"KE",
"serviceCode":"KE-MPESA-REMITTANCE",
"payerTransactionID":"{{$guid}}",
"narration":"Remittance payout",
"MSISDN":"254700000000",
"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-MPESA-REMITTANCE",
"payerTransactionID":"{{$guid}}",
"narration":"Remittance bank payout",
"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":{
"sourceCurrrency":"USD",
"destinationCurrency":"KES",
"conversionRate":"0.08882",
"localCurrencyAmount":14000.00,
"foreignCurrencyAmount":100,
"purposeOfRemmittance":"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 |
| 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 yy/MM/dd e.g. 1997/01/03 | No |
| remitter.idExpireDate | String | Sender's Identification expiry date format yy/MM/dd e.g. 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 e.g. 1997/01/03 | No |
| remitter.country | String | Sender's country of residence e.g. 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 | Yes |
| remitter.city | String | Sender's city | Yes |
| remitter.postalCode | String | Sender's postal code | No |
| remitter.zipCode | String | Sender's zip code | No |
| remitter.relationshipWithRecipient | String | Sender's relationship with recipient | Yes |
| 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.amountToSend | Double | Amount to send | 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 |