Authorization without 3DS (2D secure)
This option allows charging a card without subjecting the card to 3DS authorization.
Before you continue
HTTP accept header sent from the cardholder's browser non- 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 charge card acceptance:
- Initiate a Checkout Request
- Encrypt the payment card details.
- Formulate card charge request payload - 3DS parameter set to false.
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.
See Authorization with 3D Secure on how to encrypt the card details.
| 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" False to charge the card without 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 in the Authorization with 3D Secure section. |
| billingDetails | JSON array | Billing details as described in the Authorization with 3D Secure section |
| threeDSecure | JSON array | [OPTIONAL] External 3DS parameters passed by merchant. If passed, we assume 3D checks have been done on merchant side so we proceed to charge via 2D. 3ds parameter value above is ignored. |
The threeDSecure array consists of the following parameters
| Parameter Name | Type | Description |
|---|---|---|
| eci | string | Electronic Commerce Indicator. |
| cavv | string | Cardholder Authentication Verification Value. |
| cavvAlgorithm | string | Indicates the algorithm used to generate the CAVV value |
| xid | string | Transaction identifier resulting from authentication processing. |
| paresStatus | boolean | Transaction status result identifier. |
| enrollmentResponse | string | Check whether the card is 3ds enballed from the acquirer. |
| authenticationResponse | string | Confirm whether the 3DS check was successful. |
Example
{
"merchantTransactionID": "{{merchantTransactionID}}",
"checkoutRequestID": "{{checkoutRequestID}}",
"PayerModeID": "{{PayerModeID}}",
"languageCode": "en",
"isCvvLess": "true", //OPTIONAL - Default false
"countryCode": "NG",
"3ds": "false",
"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"
},
//OPTIONAL
"threeDsecure":{
"eci":"05",
"cavv":"563",
"cavvAlgorithm":"gshbhbdjnjdnjbd/m",
"xid":"3566hebhe",
"paresStatus":true,
"enrollmentResponse":"N",
"authenticationResponse":"N"
}
}
Response Parameters
| Parameter Name | Type | Description | Mandatory |
|---|---|---|---|
| statusCode | integer | Request status code. See full status codes details below. | TRUE |
| statusDescription | string | A description of the status provided above. | TRUE |
| accountNumber | string | Payment reference code. | TRUE |
| currencyCode | string | ISO Code currency for the transaction | TRUE |
| checkoutRequestID | integer | Unique request ID identifying the transaction provided by the checkout platform. | TRUE |
| amountPaid | double | Amount authorized on the card. | TRUE |
| MSISDN | string | Customer Mobile number. | TRUE |
| cpgTransactionID | integer | Unique transactionID on the Cellulant Payment Gateway. | FALSE |
| datePaymentReceived | string | Date the payment was authorized. | FALSE |
| payerTransactionID | string | Unique transaction reference/id from the acquirer | FALSE |
| RRNo | string | Unique code from the acquirer confirming transfer of funds. | FALSE |
| authorizationCode | string | Authorization code provided by the issuing bank. | FALSE |
| cardPrefix | integer | The last four digits of the card number. | FALSE |
Example
Successful Response
{
"statusCode": 200,
"statusDescription": "Operation done successfully",
"accountNumber": "ACC12345",
"currencyCode": "KES",
"checkoutRequestID": 576982307,
"amountPaid": 20.00,
"MSISDN": "254722100200",
"cpgTransactionID": 12345678,
"datePaymentReceived": "2022-05-01 10:20:10",
"payerTransactionID": "unique12390",
"RRNo": "098765421",
"authorizationCode": "2022",
"cardPrefix": "4040",
}
Failure Response
{
"statusCode": 216,
"statusDescription": "Insufficient funds or withdrawal limit exceeded. Fund account or retry with a different card",
"accountNumber": "ACC12345",
"currencyCode": "KES",
"checkoutRequestID": 576982307,
"amountPaid": 0.00,
"MSISDN": "254722100200",
"cpgTransactionID": 12345679,
"datePaymentReceived": "2022-05-01 10:23:10",
"payerTransactionID": "unique12391",
}
Card 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] |
Updated 2 months ago