2D authorization

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

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

Parameters

Headers

HeaderValueRequired
AuthorizationBearer <BEARER_TOKEN> Generated during the Authenticate Request.Yes
Content-Typeapplication/jsonYes
apikeyYes

Request

Parameter NameTypeDescriptionRequired
service_codeStringUnique assigned code from your sandbox or shared with youYes
country_codeStringCountry code for where the request will be processedYes
3dsStringValue should be true/false for 3ds and 2dsYes
is_cvv_lessStringValue should be true/falseNo
billing_details.address.country_codeStringCountry code for billing detail addressYes
billing_details.address.cityStringCity name for billing detail addressYes
billing_details.customer.first_nameStringCustomer first name for billing detail addressYes
billing_details.address.streetStringWhere the person livesNo
billing_details.address.stateStringThe area where the person livesNo
billing_details.customer.email_addressStringCustomer email for billing detail addressYes
billing_details.customer.surnameStringCustomer surname for billing detail addressYes
billing_details.customer.mobile_numberStringCustomer mobile number for billing detail addressYes
merchant_transaction_idStringUnique transaction id identifying the transaction as given by the merchantYes
payment_option_codeStringValue representing the payment option for the card chargeYes
source_Of_funds.cardStringValue representing for card detail in encrypted formYes
source_Of_funds.card.nameOnCardStringIt is the full name on the customer's cardYes
source_Of_funds.card.numberIntegerIt is the cardโ€™s primary account number (PANYes
source_Of_funds.card.cvvIntegerIt is the cardโ€™s verification number. Normally a 3 digit value found at the back of your cardYes
source_Of_funds.card.expiry.month source_Of_funds.card.expiry.yearIntegerIs the cardโ€™s expiry date. In moth and Year (MM/YY)Yes
localeStringLanguage codeYes
order.account_numberStringAccount number for orderYes
order.amountStringAmount of orderYes
order.currency_codeStringCurrency code of orderYes
order.descriptionStringDescription of orderYes
extra_data.checkout_request_idStringId of created checkout requestYes

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 NameTypeDescription
statusJSONObjectContains status code and description.
status_codeIntegerStatus Code of the transaction
status_descriptionStringDescription of the payment processing
resultsJSONObject
3dsStringtrue/false - false to charge the card without 3DS
msisdnLongCustomer Mobile number
amount_paidStringAmount authorized on the card
cpg_transaction_idStringUnique transactionID on the Cellulant Payment Gateway
payer_transaction_idStringUnique transaction reference/id from the acquirer
account_numberStringPayment reference
currency_codeStringISO Code currency for the transaction
tokenStringTokenized card details
card_prefixStringCard Number

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 CodeStatus Description
200Transaction was successful
203Rejected due to Address Verification System data mismatch (name, address, etc.). Retry with a different card or contact your bank to update address details
204Transaction may or may not have been successful, but MUST be canceled to comply with sanctions and law enforcement. Retry with a different card
205Transaction rejected due to CVV mismatch. Retry transaction with correct CVV
209The card is expired. Retry with a different card
210Transaction has been blocked due to fraud. Retry with a different card
211Amount is too high, too low, does not match a previous authorisation or is otherwise invalid. Retry with a different amount
212Card data (PAN, expiry date or CVV) are invalid. Retry with correct card details
213PAN is invalid. Retry with correct card PAN
214Transaction declined by acquirer. Retry with a different card
215Rejected due to problems on the issuer side. Retry with a different card
216Insufficient funds or withdrawal limit exceeded. Fund account or retry with a different card
217Card reported as lost. Contact issuing bank or retry with a different card
219Transaction not permitted to either issuer, cardholder, acquirer or merchant. Retry with a different card
220Transaction was successful for only a partial amount, void transaction and try again
222Rejected due to issues with cardholder PIN. Retry with correct card PIN or a different card
223Transaction has been rejected, please contact your card issuer or retry with a different card
224Transaction was processed, but has been flagged for manual review due to suspicion of fraud
225Card has been reported as stolen. Contact issuing bank
226Transaction timed out with unclear status; recommend to cancel and retry with a different card
616Token not found. Retry with a valid token
617Duplicate reference number. Reinitiate transaction with a unique Merchant transaction ID
629Transaction blocked due to suspected fraud. Contact card issuer for support
631Missing card number. Please provide the card number
632Missing card expiry field. Please provide the card expiry field
633Missing card expiry month field. Please provide the card expiry month field
634Missing card expiry year field. Please provide the card expiry year field
637Invalid Country Code passed. Please provide the correct country code
642Customer email is required
644Invalid card BIN format. Value should be numeric
647Card BIN is required
648Invalid card BIN length passed
651Missing card number. Please provide card number for card tokenization requests
655Incorrect card pin length. Card PIN must be four (4) digit(s)
656Unsupported request type. Set isCvvLess flag to True
660Invalid card length %s scheme. % card length should be %
661Invalid card PAN. Retry with correct card PAN
662Incorrect Expiry year length. Expiry year must be 2 digits
663Incorrect Expiry month length. Expiry month must be 2 digits
664Incorrect Expiry month. Expiry month must be value must be between 1 and 12
665Incorrect Expiry year. Expiry month must be value must be between 0 and 99
667Invalid CVV format. Card Verification Value must be a numeric value between 3 and 4 digits
668BIN passed in card issuer information does not match card BIN
671Card details is not required for delete token requests. Send only token
672Missing token. Token is required delete token requests
673Missing card pin. cardPin is required for VERVE Cards
675Unsupported request type. Set tokenizeCard flag to false
1067We are unable to process your request at the moment. Please contact support via [email protected]
1700Invalid currencyCode or currencyCode {currencyValue} has not been configured
1701Invalid or expired request. Data not found for the specified service and checkoutRequestId
1702Account Number Mismatch. Account number should be same as used in initiate checkout request
1703Invalid countryCode or countryCode {countryCodeValue} has not been configured
1704Payment Option not configured for paymentOptionCode and countryCode
1707Invalid sourceOfFunds value passed. Encrypt with valid encryption credentials
Language
Click Try It! to start a request and see the response here!