Authorization without 3DS (2D secure)

🚧
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.
agreementID	`String`	This is the enrolment ID generated by Mastercard confirming the customer has agreed to be charged for recurring payments.

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]

🚧Before you continue

Header Parameters

Request Parameters

Response Parameters

Card Status Codes

🚧
Before you continue