3D Secure with Checkout

AceHub Checkout supports 3D Secure payments for transactions paid with new cards, as well as one-click transactions made with saved cards. It uses AceHub's integrated 3DS Server, making merchant integration straightforward.

This guide describes how to implement 3D Secure and 3D Secure 2.0 with Payvision's Checkout API. Check out AceHub 3D Secure documentation and AceHub 3D Secure 2.0 documentation for more details.

Steps

1. Create a Checkout

Request a checkoutId via API. The checkoutId is valid for the next 30 min.

The field used to enable 3D Secure is threeDSecure. By default, it is false. You can enable 3D Secure for a new cards as well as one-click checkout.
Contact our Customer Support team to enable 3D Secure for your account.

a) 3DS 1 for new cards

Enable flag body.checkout.threeDSecure.

POST https://stagconnect.acehubpaymentservices.com/Gateway/v3/Checkouts
{
  "header": {
    "businessId": "{{YOUR_BUSINESS_ID}}"
  },
  "body": {
    "transaction": {
      "storeId": 1,
      "amount": 1,
      "currencyCode": "EUR",
      "authorizationMode": "payment",
      "trackingCode": "{{UNIQUE_ID}}"
    },
    "checkout": {
      "brandIds": [1010, 1020, 1030],
      "returnUrl": "{{REDIRECTION_URL}}",
      "threeDSecure": true
    }
  }
}
{
  "result": 2,
  "description": "Pending",
  "header": {
    "requestTimestamp": "2019-01-01T08:00:00Z"
  },
  "body": {
    "checkout": {
      "checkoutId": "{{CHECKOUT_ID}}",
      "redirect": {
        "method": "GET",
          "url":"https://stagconnect.acehubpaymentservices.com/gateway/v3/web/checkouts/{{CHECKOUT_ID}}"
      },
      "brandIds": [1010, 1020, 1030, 3010],
      "expirationTime": "2019-01-01T08:30:00Z",
      "threeDSecure": true
    },
    "transaction": {
      "amount": 1,
      "currencyCode": "EUR",
      "authorizationMode": "PAYMENT",
      "trackingCode": "{{UNIQUE_ID}}"
    }
  }
}

b) 3DS 1 for one-click cards:

Enable flag body.checkout.oneclick.threeDSecure

POST https://stagconnect.acehubpaymentservices.com/Gateway/v3/Checkouts
{
  "header": {
    "businessId": "{{YOUR_BUSINESS_ID}}"
  },
  "body": {
    "transaction": {
      "storeId": 1,
      "amount": 1,
      "currencyCode": "EUR",
      "authorizationMode": "payment",
      "trackingCode": "{{UNIQUE_ID}}"
    },
    "checkout": {
      "brandIds": [1010, 1020, 1030],
      "returnUrl": "{{REDIRECTION_URL}}",
      "oneClick": {
        "threeDSecure": true,
        "useCustomerTokens": true
      },
      "customer": {
        "customerid": "{{CUSTOMER_ID}}"
      }
    }
  }
}
{
  "result": 2,
  "description": "Pending",
  "header": {
    "requestTimestamp": "2019-01-01T08:00:00Z"
  },
  "body": {
    "checkout": {
      "checkoutId": "{{CHECKOUT_ID}}",
      "redirect": {
        "method": "GET",
        "url": "https://stagconnect.acehubpaymentservices.com/gateway/v3/web/checkouts/{{CHECKOUT_ID}}"
      },
      "brandIds": [1010, 1020, 1030, 3010],
      "expirationTime": "2019-01-01T08:30:00Z",
      "oneClick": {
        "threeDSecure": true,
          "useCustomerTokens": true
      }
    },
    "transaction": {
      "amount": 1,
      "currencyCode": "EUR",
      "authorizationMode": "PAYMENT",
      "trackingCode": "{{UNIQUE_ID}}"
    }
  }
}

c) 3DS 2.0 for new and/or one-click cards

  • Enable flag body.checkout.threeDSecure to perform 3DS for new card.
  • Enable flag body.checkout.oneclick.threeDSecure to perform 3DS for one-click card.
  • For 3DS 2.0, additionally specify the 3DS version in body.threeDSecure.version as "2".
POST https://stagconnect.acehubpaymentservices.com/Gateway/v3/Checkouts
{
  "header": {
    "businessId": "{{YOUR_BUSINESS_ID}}"
  },
  "body": {
    "transaction": {
      "storeId": 1,
      "amount": 1,
      "currencyCode": "EUR",
      "authorizationMode": "payment",
      "trackingCode": "{{UNIQUE_ID}}"
    },
    "checkout": {
      "brandIds": [
        1010,
        1020,
        1030
      ],
      "returnUrl": "{{REDIRECTION_URL}}",
      "threeDSecure": true,
      "oneClick": {
        "threeDSecure": true,
        "useCustomerTokens": true
      }
    },
    "threeDSecure":{
      "version": "2"
    },
    "customer": {
      "givenName": "John",
      "familyName": "Doe",
      "email": "[email protected]",
      "mobileNumber": "666777888",
      "customerid": "{{CUSTOMER_ID}}"
    },
    "dba": {
      "name": "Name",
      "city": "city"
    },
    "billingAddress": {
      "city": "Amsterdam",
      "street": "Molenpad",
      "CountryCode": "NL",
      "zip": "1016GM",
      "houseNumber": "2"
    }
  }
}
{
  "result": 2,
  "description": "Pending",
  "header": {
    "requestTimestamp": "2019-01-01T08:00:00Z"
  },
  "body": {
    "checkout": {
      "checkoutId": "{{CHECKOUT_ID}}",
      "redirect": {
        "method": "GET",
        "url": "https://stagconnect.acehubpaymentservices.com/gateway/v3/web/checkouts/{{CHECKOUT_ID}}",
          "threeDSecure":true
      },
      "brandIds": [1010, 1020, 1030, 3010],
      "expirationTime": "2019-01-01T08:30:00Z",
      "oneClick": {
        "threeDSecure": true,
         "useCustomerTokens": true
      }
    },
    "transaction": {
      "amount": 1,
      "currencyCode": "EUR",
      "authorizationMode": "PAYMENT",
      "trackingCode": "{{UNIQUE_ID}}"
    }
  }
}

2. Create the Checkout form

You can refer to our Integrations Documentation to learn how to integrate the Checkout form into your website.

In case of 3DS 1, once the customer provides their card payment details, they'll be redirected to the 3D Secure page served by the issuing bank to complete 3D authentication, after which the payment will be processed.
Note: If the issuing bank takes the liability, it may be processed as attempted 3D, bypassing the 3D authentication step.

In the case of 3DS 2.0, once the customer provides their card payment details, AceHub takes care of flagging the requested exemption. The customer can get frictionless, challenge or downgrade to 3DS 1.0 flow as described in 3DS 2.0 workflow with Payvision . AceHub then proceeds to process the authorization.

3. Get the payment status

Once the checkout is complete, our system will redirect the customer to the returnUrl (specified in checkout creation request) and the checkoutId will be appended to the URL as a query parameter. Merchants can get the Checkout status using Checkout API.

GET https://stagconnect.acehubpaymentservices.com/Gateway/v3/Checkouts/{{CHECKOUT_ID}}?businessId={{BUSINESS_ID}}
{
    "result": 0,
    "description": "Completed",
    "header": {
        "requestTimestamp": "2019-02-28T11:08:09Z"
    },
    "body": {
      "transaction": {
        "amount": 1,
          "currencyCode": "EUR",
            "authorizationMode": "PAYMENT",
              "trackingCode": "{{UNIQUE_ID}}"
      },
        "checkout": {
          "checkoutId": "{{CHECKOUT_ID}}",
            "redirect": {
              "method": "GET",
                "url": "https://stag.checkout-web.dta.payvision.app/checkouts/{{CHECKOUT_ID}}"
            },
              "brandIds": [
                1010,
                1020,
                3010,
                3200,
                3025,
                4010,
                6010,
                8010,
                3020,
                5020
              ],
                "expirationTime": "2019-02-28T11:35:20Z",
                  "tokenize": "INQUIRE",
                    "threeDSecure": false,
                      "oneClick": {
                        "tokens": [
                          "{{UNIQUE_ID}}",
                          "{{UNIQUE_ID}}"
                        ],
                          "useCustomerTokens": true,
                            "threeDSecure": false
                      }
        },
          "payments": [
            {
              "result": 0,
              "description": "Ok",
              "header": {
                "requestTimestamp": "2019-02-28T11:07:29Z",
                "requestCode": "100.a72c36d8-e7cd-46a2-9eca-282cdb779a6d"
              },
              "body": {
                "card": {
                  "approvalCode": "210474",
                  "expiryMonth": "12",
                  "expiryYear": "2099",
                  "firstSixDigits": "550000",
                  "holderName": "John Doe",
                  "lastFourDigits": "0004"
                },
                "transaction": {
                  "amount": 1,
                  "currencyCode": "EUR",
                  "action": "payment",
                  "id": "{{UNIQUE_ID}}",
                  "trackingCode": "{{UNIQUE_ID}}",
                  "brandId": 1020
                }
              }
            }
          ]
    }
}