post https://api-approval.tingg.africa/v2/remittance/payments/initiate-remittance
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": ""
}
}
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 |