Authorization with 3D Secure (3DS)
This option allows a merchant 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.
POST https://developer.tingg.africa/checkout/v2/custom/requests/direct-card-charge
Steps for authorization with 3DS:
- Initiate a Checkout Request
- Encrypt the payment card details.
- Formulate card charge request payload - 3DS parameter set to true.
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.
Parameters to be encrypted include the following:
| Parameter Name | Type | Description |
|---|---|---|
| nameOnCard | string | It is the full name on the customer's card |
| number | integer | It is the card’s primary account number (PAN) |
| cvv | integer | It is the card’s verification number. Normally a 3 digit value found at the back of your card |
| storedOnFile | String | 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. |
| month | integer | Card's expiry month (MM) |
| year | integer | Card's expiry year (YY) |
Example payload
{
"card": {
"nameOnCard": "John Doe",
"number": "5436031030606378",
"storedOnFile":"TO_BE_STORED",
"cvv": "123",
"expiry": {
"month": "12",
"year": "23"
}
}
}
See the checkout encryption snippets on how to encrypt the payload using the public key Cipher Type: RSA/ECB/Padding.
Sample Encryption Output
eUxtRVNSYmpDbG8wMWZBYXhLU3dWdk9MZ0hnUm9WaGtXTGdMenFDMnBFYU1BR08yTE5hUkdUY0J1MCtRMjZ1Y1NpaDN2ZmthYThvaHR5NElKUEtHbytPdEZjcC9jcjJqSGl2cGd0Tm5MaVVGcjFmeFpoVHdNdWxSc2dHczRYWTdUM2w1Mzhvd2cyWXM4ekZzbnlrOVV3PT0==
The parameters to will be passed in the request payload:
| 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. |
| 3ds | string | "true"/"false" True to charge the card with 3DS |
| isCvvLess | string | [OPTIONAL] parameter to be included if you would like to specify whether or not you would like to charge with cvv. Default value is "false" Set value to "true" to charge without CVV (CVV-less) |
| 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 below. |
| billingDetails | JSON array | Billing details as described below. |
| browserDetails | JSON array | Browser details as described in the Browser details references.. |
The order array consists of the following parameters
| Parameter Name | Type | Description |
|---|---|---|
| accountNumber | string | Unique reference of the order. |
| chargeAmount | double | Amount to be charged on the card. |
| currencyCode | string | Currency of the amount being transacted / charged. |
| requestDescription | string | Description of the transaction. |
The billingDetails array consists of the following parameters
| Parameter Name | Type | Description |
|---|---|---|
| address | JSON object | - |
| city | string | Billing address City |
| countryCode | string | Billing address country |
| customer | JSON object | - |
| firstName | string | Customer first name |
| surname | string | Customer last name |
| emailAddress | string | customer email address |
| mobileNumber | string | customer mobile number |
Example
{
"merchantTransactionID": "{{merchantTransactionID}}",
"checkoutRequestID": "{{checkoutRequestID}}",
"PayerModeID": "{{PayerModeID}}",
"languageCode": "en",
"isCvvLess": "true", //OPTIONAL - Default false
"countryCode": "NG",
"3ds" : "true",
"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. See full status codes details below. | 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
Successful Response
{
"statusCode": 200,
"statusDescription": "Operation done successfully",
"results": {
"redirectUrl":
"https://attest.mastercard.com/ECommercePlugin/3ds-payment.jsp?fawry-ref-number=946756284",
"type": "THREE_D_SECURE"
}
}
Failure Response
{
"statusCode": 201,
"statusDescription": "3DS Authentication failed. Retry transaction with correct OTP",
"result": null
}
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. |
| 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] |
Updated 6 months ago