3DS authorization

This option allows to charge a card without performing an actual redirect to checkout via the checkout express., You will pass the card details to charge the card and retrieve the issuer secure page.

Steps for card charge acceptance:

Initiate a checkout request
Formulate card charge request
Encrypt the payment card details under sourceOfFunds parameter

📘
Live Endpoint
https://api.tingg.africa/v3/checkout-api/direct-card

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.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
source_Of_funds.card.storedOnFile	String	Only passed for card enrolment. Can either be TO_BE_STORED or null. Where if you pass TO_BE_STORED you will be given back an agreement ID in your callback that can then be included in subsequent 2D charge requests.	No
locale	String	Language code	Yes
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
browser_details.acce	String	Browser detail	Yes
pt_header	String	Browser detail	Yes
browser_details.screen_color_depth	String	Browser detail	Yes
browser_details.language	String	Browser detail	Yes
browser_details.screen_height	String	Browser detail	Yes
browser_details.screen_width	String	Browser detail	Yes
browser_details.timezone	String	Browser detail	Yes
browser_details.java_enabled	String	Browser detail	Yes
browser_details.javascript_enabled	String	Browser detail	Yes
browser_details.ip_address	String	Browser detail	Yes
browser_details.user_agent	String	Browser detail	Yes

Request Body

{
    "service_code" : "SERVICE9",
    "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": "254765121298"
        }
    },
    "merchant_transaction_id": "MT5468798",
    "payment_option_code": "ECO_CARD",
    "source_Of_funds": "RVlQZHRDdjNhMm9IeitjOWdZQ3o2QUo5d1I0SlRsSGV4bG9TamtETUlZK09xSitDampNTHNpemVSS1g0dEl1SjNVMW91S3RRT0lqUjlSM3V3TFhYVFRwSFRPS2o2TFdkUzJEekdERUErMkdmVWVpMGZOdzVQOXhYdzNVV3NJMm9OM3BoUVg5MHoycSthblk4eWwwelBMWU1PTFV5L05KWlFubHM3REpEWVVvPQ==",
    "locale": "en",
    "order": {
        "account_number": "ASDF7E",
        "amount": "1000.00",
        "currency_code": "KES",
        "description": "Order XX Purchase"  
    },
   "extra_data":{
       "checkout_request_id":"116507"   
    },
    "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"
    }
}

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

📘
The encryption should done for card information data below

Sample encrypted parameters

 {
    "card": {
        "nameOnCard": "John Doe",
        "number": "5436031030606378",
        "storedOnFile":"TO_BE_STORED",
        "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	The response status code
status_description	String	Exact description of the status
results	JSONObject	Null when request fails
redirect_url	String	Redirect URL or page to redirect your client for payment authentication by your issuing bank.
type	String	The type of response

Response Body

{
    "status": {
        "status_code": 200,
        "status_description": "Operation done successfully"
    },
    "results": {
        "redirect_url": "https://direct-card-api.dev.tingg.africa/v1/charge/redirect/MT5468792",
        "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

📘Live Endpoint

Parameters

Headers

Request

Request Body

Encryption Payload

📘

Sample encrypted parameters

Encryption Output

Response

Response Body

Status Codes

📘
Live Endpoint