post
https://api-approval.tingg.africa/v2/remittance/payments/initiate-remittance
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
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": {
"pushToOriginator": true,
"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 (List of service codes) | 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 | Any extra parameter or information you need to pass in a key-value JSON format, i.e., callBackUrl | no |
| extraData.pushToOriginator | boolean | Set the value as "true" in order to enable callbacks | no |
| extraData.callbackUrl | string | Provide your callback URL | no |
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 |