3D-Secure
3D-secure processing flow consists of 4 parts:
Phase 1 → provide to the client RedirectURL and PaReq for performing request to Issuer Bank page
Phase 2 → perform Post request to Issuer Bank page. Receive paResp by the client from Issuer Bank
Phase 3 → provide to the client threeDSToken, eci, xid, cavv
Phase 4 → process transaction with threeDSToken or eci, xid, cavv
Phase 1. check3DSEnrollment method
Phase 1. check3DSEnrollment method
“check3DSEnrollment” is the method used to initiate a 3DS authentication.
“check3DSEnrollment” Endpoint:
Sandbox URL: TxWs/ATPayTxWS.svc/json/сheck3DSEnrollment
Production URL: TxWs/ATPayTxWS.svc/json/сheck3DSEnrollment
Request Parameters
| Name | Type | Required | Description | |||||||||||||||||||||
| subAccountId | integer | ✓ | Sub-Account identifier. must be greater than 0. | |||||||||||||||||||||
| accountId | integer | ✓ | Platform Account identifier. must be greater than 0. | |||||||||||||||||||||
| amount | decimal | ✓ | Transaction amount. value ≥ 0 (2 decimal places) | |||||||||||||||||||||
| currency | enum | ✓ | CurrencyTypeId. Available Values:
| |||||||||||||||||||||
| creditCard | object | ✓ | Credit Card data object. |
Response Parameters
| Name | Type | Required | Description | |
| orderId | string | ✓ | Transaction identifier. | |
| responseCode | integer | ✓ | System response code. | |
| responseDescription | string | ✓ | System response code description. | |
| paymentToken | string | ✓ | System response code description. | |
| redirectURL | string | ✓ | URL to the issuer bank page. | |
| paReq | string | ✓ |
Phase 2. Request to Issuer Bank page
The payment page should redirect the client to the redirectURL provided in check3DSEnrollment response via an HTTP POST request with the following parameters:
- The variable PaReq containing the value received from the check3DSEnrollment response.
- The variable MD containing the value of orderId received from the check3DSEnrollment response.
- The variable TermUrl containing the value of a return URL for 3DS handling on your server.
The customer fills out his code on the bank URL.
The bank URL redirects the customer towards the 3DS handling URL specified by the merchant (in TermUrl) via an HTTP POST request with the following parameters:
- The variable paRes which holds the value to be submitted in PaResp parameter of the check3DSPaymentResponse call
- The variable MD with the value of the submitted order ID.
Phase 3. check3DSPaymentResponse method
“check3DSPaymentResponse” is the method used to verify a 3DS result.
“check3DSPaymentResponse” Endpoint:
Sandbox URL: https://sandbox.4levers.com/TxWs/ATPayTxWS.svc/json/check3DSPaymentResponse
Production URL: https://transactions.4levers.com/ATPayTxWS.svc/json/check3DSPaymentResponse
Request Parameters
| Name | Type | Required | Description | |
| subAccountId | integer | ✓ | Sub-Account identifier. must be greater than 0. | |
| accountId | integer | ✓ | Platform Account identifier. must be greater than 0. | |
| orderId | string | ✓ | Id to match the transaction | |
| paResp | string | ✓ | Request value from issuer bank |
Response Parameters
| Name | Type | Required | Description | |
| orderId | string | ✓ | Transaction Id of the Phase 2. | |
| responseCode | integer | ✓ | System response code. | |
| responseDescription | string | ✓ | System response code description. | |
| token | string | ✓ | 3D – Secure token. This parameter is used to indicate if a transaction has been authenticated | |
| eci | string | ✓ | ECI indicates the result of 3D-secfure authentication process (verification successful/ verification attempted/ unable to verify) | |
| xid | string | ✓ | XID is the id (or code) of the particular authentication | |
| cavv | string | ✓ | CAVV is the authentication verification value |
Phase 4. Processing transaction with 3D-Secure
Processing transaction Authorization and Charge can be processed with threeDSecure Token and eci, xid, cavv (depends on payment processor). Look for information about “threeDSecure” object parameters in Auth or Charge sections.
Endpoints:
Sandbox URL: https://sandbox.4levers.com/TxWs/ATPayTxWS.svc/json/Transaction
Production URL: https://transactions.4levers.com/ATPayTxWS.svc/json/Transaction
Authorization
Authorization is not an actual charge; it is only a reservation of a certain amount. Authorizations help reduce the risk of fraudulent transactions and credit card misuse.
Authorization transaction confirms that the Buyer has provided valid payment information and reserves sufficient funding to perform the transaction.
Following a successful Authorization transaction, you will receive a confirmation with the transaction identifier numberTransactionID":"1010000000139894". Use this identifier as a parent transaction identifier (OriginalTransactionId) for all subsequent transactions that derive from the current transaction.
Authorizations may also serve to reserve an amount of money on a credit card balance for security and verification purposes until the actual Deposit transaction is executed.
Authorization transaction may be followed by:
Void (Cancel Authorization) transaction. In this type of transaction, the amount reserved by the Authorization transaction is being released back to the credit card balance.
Released funds are previously reserved funds that now have become available.
Partial Void (Partial Cancel Authorization) transaction. This transaction involves the partial release of the amount reserved by the parent Authorization transaction.
Capture transaction. Capture transaction transfers the previously reserved amount from the buyer’s bank account to the acquirer bank account.
Request Parameters
| Name | Type | Required | Description | |||||||||||||||||||||
| accountId | integer | ✓ | Platform Account identifier. Must be greater than 0. | |||||||||||||||||||||
| amount | decimal | ✓ | Transaction amount. value ≥ 0 (2 decimal places) | |||||||||||||||||||||
| billingAddress | object | optional | User Billing Address data object. | |||||||||||||||||||||
| billingOverride | object | optional | Data object that contains an array of billingFee objects. | |||||||||||||||||||||
| creditCard | object | conditional | Credit Card data object. Required if Payment method = CreditCard; | |||||||||||||||||||||
| ach | object | conditional | ACH data object. Required if Payment method = ACH. | |||||||||||||||||||||
| currency | enum | ✓ | CurrencyTypeId. Available Values:
| |||||||||||||||||||||
| merchantData | object | optional | Merchant Data data object. | |||||||||||||||||||||
| entryMode | integer | optional | Nullable Transaction entry mode numerical value. | |||||||||||||||||||||
| paymentMethod | enum | ✓ | PaymentMethod enum values. Available Values:
| |||||||||||||||||||||
| processorData | object | optional | Processor Data data object. | |||||||||||||||||||||
| subAccountId | integer | ✓ | Sub-Account identifier. value ≥ 0 | |||||||||||||||||||||
| terminalId | string | optional | Terminal identifier. MaxLength(20) | |||||||||||||||||||||
| transactionMethod | enum | optional | transactionMethodId. Available Values:
| |||||||||||||||||||||
| type | enum | ✓ | TransactionTypeId. Authorization | |||||||||||||||||||||
| threeDSecure | object | optional | 3D-Secure data object. |
//Request example
{
"subAccountId": "Sub-Account Id",
"accountId": "Platform Account Id",
"amount": 13,
"currency": "USD",
"creditCard": {
"number": "4111111111111",
"expirationDate": "1220",
"nameOnCard": "Eleanor Johansson",
"type": "Visa",
"cvv": "123",
"tokenization": {
"type": "Internal",
"token": "1232535645746"
}
}
}
//Response example
{
"orderId":"1234560000789",
"responseCode": 0,
"responseDescription":"Operation successful",
"paymentToken": "...",
"redirectURL": "https://example.aspx?ReqType=0",
"paReq": "eNpVUsFu2zAMvesrchjQ"
}
//Request example
{
"subAccountId": "Sub-Account Id",
"accountId": "Account Id",
"orderId": "1618001128118361545",
"paResp":"eJzNWVmvm9iy/it"
}
//Response example
{
"orderId": "1666001130505655463",
"responseCode":"0",
"responseDescription":"Operation successful",
"token": "8e86aef68037e8849980"
"eci": "3",
"xid": "857e2347c329eec31c75",
"cavv":"645sd54ad5a5sd65",
"result": "verified"
}