Generate Token
Generates a re-usable token based on the customer card details
POST https://developer.tingg.africa/checkout/v2/custom/requests/save-token
Header Parameters
Header | Value | Required |
---|---|---|
Authorization | Bearer <Bearer_Token> generated during authenticate request in step 1. | YES |
Content-Type | application/json | YES |
Request Parameters
The card details will need to be encrypted and the encrypted string passed under the sourceOfFunds parameter in the final payload.
See Authorization with 3D Secure on how to encrypt the card details.
Parameter Name | Type | Description |
---|---|---|
serviceCode | string | Unique code identifier for the merchant's service in use as provided on the checkout platform. |
merchantTransactionID | string | Unique transaction ID identifying the transaction as given by the merchant. |
payerModeID | integer | This is a number representing the payment option client and the mode in use e.g. using a mobile money client paying via STK push. This will be provided as part of the payment options |
languageCode | string | 2 letter code for the language used for the transaction. |
countryCode | string | The ISO 3166-1 alpha-2 code of the country you wish to collect payment for. |
checkoutRequestID | integer | A unique transaction ID identifying the transaction logged in the checkout platform. |
sourceOfFunds | string | Encrypted card details |
order | JSON array | Order details as described in the Authorization with 3D Secure section. |
billingDetails | JSON array | Billing details as described in the Authorization with 3D Secure section |
browserDetails | JSON array | Browser details as described in the Browser details reference. |
Example
{
"merchantTransactionID": "{{merchantTransactionID}}",
"checkoutRequestID": "{{checkoutRequestID}}",
"PayerModeID": "{{PayerModeID}}",
"languageCode": "en",
"countryCode": "NG",
"serviceCode": "{{service_code}}",
"order": {
"accountNumber": "ASDF7E",
"chargeAmount": "1000.00",
"currencyCode": "KES",
"requestDescription": "Order XX Purchase"
},
"sourceOfFunds": "eUxtRVNSYmpDbG8wMWZBYXhLU3dWdk9MZ0hnUm9WaGtXTGdMenFDMnBFYU1BR08yTE5hUkdUY0J1MCtRMjZ1Y1NpaDN2ZmthYThvaHR5NElKUEtHbytPdEZjcC9jcjJqSGl2cGd0Tm5MaVVGcjFmeFpoVHdNdWxSc2dHczRYWTdUM2w1Mzhvd2cyWXM4ekZzbnlrOVV3PT0==",
"billingDetails": {
"address": {
"city": "Nairobi",
"countryCode": "NG"
},
"customer": {
"firstName": "Gunnar",
"emailAddress": "[email protected]",
"surname": "Stewart",
"mobileNumber": "254765121298"
}
},
"browserDetails": {
"acceptHeader": "text\/html",
"screenColorDepth": "24",
"language": "en-US",
"screenHeight": "768",
"screenWidth": "1366",
"timezone": "-180",
"javaEnabled": "false",
"javascriptEnabled": "true",
"ipAddress": "192.123.12.1",
"userAgent": "Firefox 105.0"
}
}
Response Parameters
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
statusCode | integer | Response status code. | TRUE |
statusDescription | string | A description of the status provided above. | TRUE |
results | JSON array | Null when request fails. | |
results.redirectUrl | string | Url to redirect your client for payment authentication by your issuing bank | FALSE |
results.type | string | The type of response | FALSE |
Example
{
"statusCode": 200,
"statusDescription": "Operation done successfully",
"results": {
"redirectUrl": "https://direct-card-api.dev.tingg.africa/v1/secure3d/auth/mawiteoka75867yuJUJU",
"type": "THREE_D_SECURE"
}
}
Success
A token will be generated and sent as a query param on the redirectUrl
Sample: https://www.google.com/?token=xxxxxxxxxxxxxxxxxxxxxxxxxx
Card Status Codes
Status Code | Status Description |
---|---|
200 | Transaction was successful |
201 | 3DS Authentication failed. Retry transaction with correct OTP |
203 | Rejected due to Address Verification System data mismatch (name, address, etc.). Retry with a different card or contact your bank to update address details |
204 | Transaction may or may not have been successful, but MUST be canceled to comply with sanctions and law enforcement. Retry with a different card |
205 | Transaction rejected due to CVV mismatch. Retry transaction with correct CVV |
209 | The card is expired. Retry with a different card |
210 | Transaction has been blocked due to fraud. Retry with a different card |
211 | Amount is too high, too low, does not match a previous authorisation or is otherwise invalid. Retry with a different amount |
212 | Card data (PAN, expiry date or CVV) are invalid. Retry with correct card details |
213 | PAN is invalid. Retry with correct card PAN |
214 | Transaction declined by acquirer. Retry with a different card |
215 | Rejected due to problems on the issuer side. Retry with a different card |
216 | Insufficient funds or withdrawal limit exceeded. Fund account or retry with a different card |
217 | Card reported as lost. Contact issuing bank or retry with a different card |
219 | Transaction not permitted to either issuer, cardholder, acquirer or merchant. Retry with a different card |
220 | Transaction was successful for only a partial amount, void transaction and try again |
222 | Rejected due to issues with cardholder PIN. Retry with correct card PIN or a different card |
223 | Transaction has been rejected, please contact your card issuer or retry with a different card |
224 | Transaction was processed, but has been flagged for manual review due to suspicion of fraud |
225 | Card has been reported as stolen. Contact issuing bank |
226 | Transaction timed out with unclear status; recommend to cancel and retry with a different card |
602 | Invalid payment token passed. Merchant to review and send correct token |
608 | 3DS Authentication failed, unable to redirect customer to card issuer page. Retry with a different card |
609 | Token not allowed for 3DS transaction |
610 | Unable to complete the payment. Please try again |
611 | Payment Declined. Your card is not 3DS Enabled. Contact your bank. |
616 | Token not found. Retry with a valid token |
617 | Duplicate reference number. Reinitiate transaction with a unique Merchant transaction ID |
629 | Transaction blocked due to suspected fraud. Contact card issuer for support |
631 | Missing card number. Please provide the card number |
632 | Missing card expiry field. Please provide the card expiry field |
633 | Missing card expiry month field. Please provide the card expiry month field |
634 | Missing card expiry year field. Please provide the card expiry year field |
637 | Invalid Country Code passed. Please provide the correct country code |
642 | Customer email is required |
644 | Invalid card BIN format. Value should be numeric |
647 | Card BIN is required |
648 | Invalid card BIN length passed |
651 | Missing card number. Please provide card number for card tokenization requests |
655 | Incorrect card pin length. Card PIN must be four (4) digit(s) |
656 | Unsupported request type. Set isCvvLess flag to True |
660 | Invalid card length %s scheme. % card length should be % |
661 | Invalid card PAN. Retry with correct card PAN |
662 | Incorrect Expiry year length. Expiry year must be 2 digits |
663 | Incorrect Expiry month length. Expiry month must be 2 digits |
664 | Incorrect Expiry month. Expiry month must be value must be between 1 and 12 |
665 | Incorrect Expiry year. Expiry month must be value must be between 0 and 99 |
667 | Invalid CVV format. Card Verification Value must be a numeric value between 3 and 4 digits |
668 | BIN passed in card issuer information does not match card BIN |
671 | Card details is not required for delete token requests. Send only token |
672 | Missing token. Token is required delete token requests |
673 | Missing card pin. cardPin is required for VERVE Cards |
675 | Unsupported request type. Set tokenizeCard flag to false |
701 | Secure3D Authentication Pending. Prompt user for OTP for Verve Card |
1067 | We are unable to process your request at the moment. Please contact support via [email protected] |
Updated 9 months ago