post https://api-approval.tingg.africa/v3/checkout-api/save-card-and-charge
Card details are used for the first time. The card will be charged and a token will be generated and sent back to the merchant.
Headers
| Header | Value | Required |
|---|---|---|
| Authorization | Bearer <BEARER_TOKEN> Generated during the authenticate request | YES |
| Content-Type | application/json | YES |
| apikey | YES |
Request
| Parameter Name | Type | Description | Required |
|---|---|---|---|
| service_code | string | Unique assigned code from your sandbox or shared with you | Yes |
| merchant_transaction_id | string | Unique transaction ID identifying the transaction as given by the merchant. | Yes |
| payment_option_code | integer | Value representing the payment option for the card change | Yes |
| locale | string | It is the language used for the transaction | Yes |
| country_code | string | Country code for where the request will be processed | Yes |
| is_cvv_less | string | Value should be true/false for 3ds and 2ds | No |
| 3ds | string | true/false - false to charge the card without 3DS | Yes |
| extra_data | JSON Object | Extra Details | Yes |
| extra_data.checkout_request_id | integer | Unique request ID identifying the transaction provided by the checkout platform. | Yes |
| order | JSON Object | Order Details | Yes |
| order.account_number | String | Is the unique reference of the order | Yes |
| order.amount | double | It is the amount to be charged on the card | Yes |
| order.currency_code | string | Is the currency of the amount being transacted / charged | Yes |
| order.description | string | It contains a description of the transaction | Yes |
| source_Of_funds.card | String | Source of funds details - card details | Yes |
| source_Of_funds.card.nameOnCard | string | It is the full name on the customer's card | Yes |
| source_Of_funds.card.number | integer | It is the card’s primary account number (PAN) | Yes |
| source_Of_funds.card.cvv | integer | It is the card’s verification number. Normally a 3 digit value found at the back of your card | Yes |
| source_Of_funds.card.expiry.month source_Of_funds.card.expiry.year | integer | Is the card’s expiry date. In moth and Year (MM/YY) | Yes |
| billing_details | JSON Array | Billing Details | Yes |
| billing_details.address | JSON Array | Bill Address Details | Yes |
| billing_details.address.city | string | Billing address, City | Yes |
| billing_details.address.country_code | string | Billing address, Country | Yes |
| billing_details.customer.first_name | string | It is the customer’s first name | Yes |
| billing_details.customer.surname | string | It is the customer’s last name | Yes |
| billing_details.customer.email_address | string | It is the customer’s email address that is tied to the card token generated | Yes |
| billing_details.customer.mobile_number | string | It is the customer’s mobile number. | Yes |
| browser_details | JSON Array | Contains browser details | Yes |
| browser_details.accept_header | string | This represent http data format | Yes |
| browser_details.screen_color_depth | string | It's the maximum number of colors that can be displayed | Yes |
| browser_details.language | string | This indicates browser language | Yes |
| browser_details.screen_height | string | The is the value of browser window layout viewport | Yes |
| browser_details.screen_width | string | This is the value of browser window layout viewport | Yes |
| browser_details.timezone | string | It's the browser region where the same standard time is used | Yes |
| browser_details.java_enabled | boolean | This specify if browser | Yes |
| browser_details.javascript_enabled | boolean | This specify if browser supports javascript or not | Yes |
| browser_details.ip_address | string | It uniquely identify the device on the internet | Yes |
| browser_details.user_agent | string | This field contains the exact content of the HTTP User-Agent header | Yes |
Request Body
{
"service_code": "{{service_code}}",
"country_code": "KEN",
"3ds": "true",
"billing_details": {
"address": {
"country_code": "KEN",
"city": "Kenya"
},
"customer": {
"first_name": "Gunnar",
"email_address": "[email protected]",
"surname": "Stewart",
"mobile_number": "254791498482"
}
},
"merchant_transaction_id": "MT546871074",
"payment_option_code": "ECO_CARD",
"source_Of_funds": "RVlQZHRDdjNhMm9IeitjOWdZQ3o2QUo5d1I0SlRsSGV4bG9TamtETUlZK09xSitDampNTHNpemVSS1g0dEl1SjNVMW91S3RRT0lqUjlSM3V3TFhYVFRwSFRPS2o2TFdkUzJEekdERUErMkdmVWVpMGZOdzVQOXhYdzNVV3NJMm9OM3BoUVg5MHoycSthblk4eWwwelBMWU1PTFV5L05KWlFubHM3REpEWVVvPQ==",
"locale": "en",
"order": {
"account_number": "31318461285",
"amount": "1000.00",
"currency_code": "KES",
"description": "Order XX Purchase"
},
"extra_data": {
"checkout_request_id": 565
},
"browser_details": {
"accept_header": "text/html",
"screen_color_depth": "24",
"language": "en-US",
"screen_height": "768",
"screen_width": "1366",
"timezone": "-180",
"java_enabled": "false",
"javascript_enabled": "true",
"ip_address": "192.123.12.1",
"user_agent": "Firefox 105.0"
}
}
Response
| Parameter Name | Type | Description |
|---|---|---|
| status | JSON Object | Contains status code and description |
| status_code | integer | The response status code |
| status_description | string | Exact description of the status |
| results | JSON Array | Null when request fails |
| results.redirect_url | URL String | Redirect URL or page to redirect your client for payment authentication by your issuing bank. |
| results.type | string | The type of response |
{
"status": {
"status_code": 200,
"status_description": "Operation done successfully"
},
"results": {
"redirect_url": "https://direct-card-api.dev.tingg.africa/v1/secure3d/auth/MT546871097",
"type": "THREE_D_SECURE"
}
}
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. |
| 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 |
| 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] |
| 1700 | Invalid currencyCode or currencyCode {currencyValue} has not been configured |
| 1701 | Invalid or expired request. Data not found for the specified service and checkoutRequestId |
| 1702 | Account Number Mismatch. Account number should be same as used in initiate checkout request |
| 1703 | Invalid countryCode or countryCode {countryCodeValue} has not been configured |
| 1704 | Payment Option not configured for paymentOptionCode and countryCode |
| 1707 | Invalid sourceOfFunds value passed. Encrypt with valid encryption credentials |