Guides
Sign UpLog InLearning CenterPlatform StatusPostman Collection

Card Issuer 3DS

Suggest Edits

Card Issuer 3DS

"Three Domain Secure" (3DS) is a protocol designed to be an additional security layer for credit and debit card transactions when there is no physical card present, such as in online purchases.

When a merchant initiates the 3DS process the Synctera platform responds according to your configuration. You may specify the desired 3DS behaviour at the card product level or on a per-request basis.

Card Product

Each product can be configured with a three_ds_policy. This field has two possible values: SMS_OTP and EXEMPT. If no value is specified, the default is SMS_OTP.

If you choose SMS_OTP then for each 3DS process involving the card product the cardholder will receive an SMS message with a one-time code which they must then supply to the merchant to verify their identity. The SMS will be sent to the customer's phone number that is stored in the platform.

If you choose EXEMPT then each 3DS process involving the card product will succeed with no further steps.

You may override the card product's 3DS policy by implementing a decision gateway.

Decision Gateway

3DS decision gateways allow you to make real-time decision about each 3DS request. 3DS gateways are independent entities in the Synctera platform which can be associated with any number of card products. These associations are defined by the three_ds_decision_gateways endpoints, not the card product endpoints.

Creation

Create a 3DS decision gateway by calling POST /v1/cards/three_ds_decision_gateways with a body like this:

{
  "is_active": true,
  "decision_url": "https://your.server/3ds_decision",
  "card_products": [
    "2957a146-ce3b-4d04-8328-ab3ea6e76cac"
  ],
  "fallback_decision": "EXEMPT",
  "custom_headers": {
    "X-Custom-Data": "arbitrary value"
  }
}

Every time the Synctera platform makes a 3DS decision for a card from the card products you specify, it will now attempt to send a POST request to your decision_url. The request will include all the custom_headers key-value pairs you specify as HTTP headers in the request.

Custom headers are optional to use as you see fit. For the purpose of authenticating requests, rather than using custom headers, you can create a signature secret for request validation and then check the Synctera-Signature HTTP header of each request to your gateway.

The fallback_decision will be used if something goes wrong and the Synctera platform can't get a response from your decision endpoint or the request times out. The values for fallback_decision are the same as the three_ds_policy options for a card product (SMS_OTP and EXEMPT) and have the same meaning.

If an active decision gateway is configured for a card product, then the API responses for that card product will indicate that the three_ds_policy is DECISION_GATEWAY. This means that the decision gateway overrides the three_ds_policy of the card product and if the Synctera platform can't get a response from the decision gateway it will use the gateway's fallback_decision rather than the card product's three_ds_policy.

3DS Decision Request

The body of the request to your 3DS decision server will look like this:

{
  "card_id": "f8c84f73-91a5-4dfe-9c12-a35bfa1df716",
  "card_product_id": "2957a146-ce3b-4d04-8328-ab3ea6e76cac",
  "acs_transaction_id": "a0c165f9-23ae-408c-b8c3-a7c486750b1e",
  "authentication_request_type": "PAYMENT",
  "client_ip_address": "10.1.2.3",
  "device_channel": "BROWSER",
  "transaction_amount": 6187,
  "currency_code": "USD",
  "transaction_type": "PAYMENT",
  "transaction_sub_type": "PURCHASE",
  "merchant": {
    "name": "Best Buy",
    "country_code": "840",
    "id": "345954985882",
    "category_code": "5732"
  }
}

The transaction_amount is in minor units of the currency (in this case, cents). The currency is specified in the currency_code field as a 3 character alphabetical code.

authentication_request_type is one of PAYMENT, RECURRING, INSTALLMENT, ADD_CARD, MAINTAIN_CARD or EMV_CARDHOLDER_VERIFICATION.

device_channel is one of BROWSER, APP_BASED or THREEDS_REQUESTER_INITIATED.

transaction_type is either PAYMENT or NON_PAYMENT.

transaction_sub_type is one of PURCHASE, ACCOUNT_VERIFICATION, ACCOUNT_FUNDING, QUASI_CASH or PREPAID_ACTIVATION_AND_LOAD.

The merchant.country_code is specified as the ISO 3166-1 three-digit numeric country code.

3DS Decision Response

To indicate your 3DS decision, your 3DS decision server responds with HTTP status OK (200) and writes a single field the response body. For example:

{
  "decision": "EXEMPT"
}

The allowed values for your decision are SMS_OTP and EXEMPT. These values have the same meaning as described above for the three_ds_policy of a card product.

If the Synctera platform sees a response status code other than 200 or can't decode the response body then it will use the gateway's fallback_decision.

Updated 10 months ago