post https://api-approval.tingg.africa/v3/checkout-api/direct-card
This option allows charging a card without subjecting the card to 3DS authorization.
info:
HTTP accept header sent from the cardholder's browserNon- 3DS cards allow for non-payment authentication that allows the protocol to be used in more than just traditional browser-based payments.
This API will be available by approval only on production.
Steps for card charge acceptance:
- Initiate a checkout request
- Formulate card charge request- 3ds parameter is set to false
- Encrypt the payment card details under sourceOfFunds parameter
Live Endpoint
Parameters
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 |
| country_code | String | Country code for where the request will be processed | Yes |
| 3ds | String | Value should be true/false for 3ds and 2ds | Yes |
| is_cvv_less | String | Value should be true/false | No |
| billing_details.address.country_code | String | Country code for billing detail address | Yes |
| billing_details.address.city | String | City name for billing detail address | Yes |
| billing_details.customer.first_name | String | Customer first name for billing detail address | Yes |
| billing_details.address.street | String | Where the person lives | No |
| billing_details.address.state | String | The area where the person lives | No |
| billing_details.customer.email_address | String | Customer email for billing detail address | Yes |
| billing_details.customer.surname | String | Customer surname for billing detail address | Yes |
| billing_details.customer.mobile_number | String | Customer mobile number for billing detail address | Yes |
| merchant_transaction_id | String | Unique transaction id identifying the transaction as given by the merchant | Yes |
| payment_option_code | String | Value representing the payment option for the card charge | Yes |
| source_Of_funds.card | String | Value representing for card detail in encrypted form | 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 |
| locale | String | Language code | Yes |
| agreement_id | String | Enrolment reference given back for card stored on file | No |
| order.account_number | String | Account number for order | Yes |
| order.amount | String | Amount of order | Yes |
| order.currency_code | String | Currency code of order | Yes |
| order.description | String | Description of order | Yes |
| extra_data.checkout_request_id | String | Id of created checkout request | Yes |
Request Body
{
"service_code" : "{{service_code}}",
"country_code": "KEN",
"3ds":"false",
"billing_details": {
"address": {
"country_code": "KEN",
"city": "Kenya"
},
"customer": {
"first_name": "Gunnar",
"email_address": "[email protected]",
"surname": "Stewart",
"mobile_number": "254791498482"
}
},
"merchant_transaction_id": "MT546871010179",
"payment_option_code": "ECO_CARD",
"source_Of_funds": "S3hWM1RFcS9pV0xRZXRKWlNhQ3dYMnE4bkI4dE1udnNrTnlMYXZDVnY4R0x1c2x3RGlhMmVpMnBLOHlkSXdYc1RGV3l1SEpqSEtOTjNlVlNyL05MODhlUlViTXJHTTVSeDF0R0U5c2hPS290N2hLK09tSUlVWklWNC9nRlNBVTlISGwreDBkdVIzdXRRY2dxdEFvYlBzTWdsVkYzOGNpNkJuYkwrUFlYSis0PQ==",
"locale": "en",
"order": {
"account_number": "31318461285",
"amount": "1000.00",
"currency_code": "KES",
"description": "Order XX Purchase"
},
"extra_data":{
"checkout_request_id": 122735
}
}
Encryption Payload
In order to perform a card charge on Direct card API, you need to encrypt your payment information and call our /charge endpoint with the encrypted payload.
Let’s encrypt the Source Of Funds data parameter in the request above using the public key Cipher Type: AES/CBC/PKCS5Padding. See Checkout encryption snippet
info:
The encryption should done for card information data below
Sample encrypted parameters
{
"card": {
"nameOnCard": "John Doe",
"number": "5436031030606378",
"cvv": "123",
"expiry": {
"month": "12",
"year": "23"
}
}
}
Encryption Output
S2R4eEM4RjgyY010NWwxZmF0RTlZQTJXcmZIQWRmM1RFa0JoVTQ5YVdobTJqRDFiNVIvUGtlK0g4N2tlK3NCTVlLR3lYc1l4cTl5R0ZJQ3k2U0gxTzZSVnJ2Q24zallndkFvZVJGV3Y3N2tEeEloN0RpdXQrQWF5VUYrWVVBdlVDNm1RUG8xK2dSNEpOSWVldldQMzRSOHVnbzJmQzZVVmJDcFgzU1U0Z2dzPQ==
Response
| Parameter Name | Type | Description |
|---|---|---|
| status | JSONObject | Contains status code and description. |
| status_code | Integer | Status Code of the transaction |
| status_description | String | Description of the payment processing |
| results | JSONObject | |
| 3ds | String | true/false - false to charge the card without 3DS |
| msisdn | Long | Customer Mobile number |
| amount_paid | String | Amount authorized on the card |
| cpg_transaction_id | String | Unique transactionID on the Cellulant Payment Gateway |
| payer_transaction_id | String | Unique transaction reference/id from the acquirer |
| account_number | String | Payment reference |
| currency_code | String | ISO Code currency for the transaction |
| token | String | Tokenized card details |
| card_prefix | String | Card Number |
| agreement_id | String | This is the enrolment ID generated by Mastercard confirming the customer has agreed to be charged for recurring payments |
Response Body
{
"status": {
"status_code": 200,
"status_description": "Card Charge Success"
},
"results": {
"3ds": "false",
"msisdn": 254791498482,
"amount_paid": "1000.00",
"cpg_transaction_id": "405696965049847808",
"payer_transaction_id": "68779_302412268342",
"account_number": "31318461289",
"currency_code": "KES",
"token": null,
"card_prefix": "512345xxxxxx0008",
"rrn": "302412268342"
}
}
Status Codes
| Status Code | Status Description |
|---|---|
| 200 | Transaction was successful |
| 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 |
| 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 |
| 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 |