Making a 3D Secure Payment

Learn about 3D Secure, another layer of security you can use to make sure purchases are legitimate.


Card networks have enhanced ways of verifying the identities of buyers. One option available is 3D Secure which asks either a challenge question or requires the buyer to log into their bank to complete the payment. This is used often in Europe.

By enabling 3D Secure on a transaction, you're shifting the liability of a chargeback from the seller to the buyer's issuing bank.

When you enable 3D Secure, typically the buyer will be shown an additional authentication page on their bank's website. The buyer then authenticates the transaction with their bank to process the payment.

attention

To handle 3D Secure payments through Finix, you will need your own 3D Secure Vendor. These vendors are responsible for generating the values that get passed as part of 3d_secure_authentication, which are required to process 3D Secure payments.

You can create a 3D secure payment as a part of:

3D Secure Authorization

To Authorize a 3D secure payment, create an Authorization and provide the 3d_secure_authentication data:

Copy
Copied
curl https://finix.sandbox-payments-api.com/authorizations \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "3d_secure_authentication": {
	        "cardholder_authentication": "BwABBJQ1AgAAAAAgJDUCAAAAAAA=",
	        "electronic_commerce_indicator": "AUTHENTICATED",
	        "transaction_id": "EaOMucALHQqLAEGAgk"
	    },
	    "amount": 100,
	    "currency": "USD",
	    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
	    "source": "PIe2YvpcjvoVJ6PzoRPBK137",
	    "tags": {
	        "order_number": "21DFASJSAKAS"
	    }
	}'

A successful response returns 201 and the created Authorization.

Copy
Copied
{
  "id" : "AU4gmGGitJe2raohfb3VNeQ",
  "created_at" : "2022-10-10T06:46:19.87Z",
  "updated_at" : "2022-10-10T06:46:20.17Z",
  "3ds_redirect_url" : null,
  "additional_buyer_charges" : null,
  "additional_healthcare_data" : null,
  "address_verification" : "POSTAL_CODE_AND_STREET_MATCH",
  "amount" : 100,
  "amount_requested" : 100,
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "currency" : "USD",
  "expires_at" : "2022-10-17T06:46:19.87Z",
  "failure_code" : null,
  "failure_message" : null,
  "idempotency_id" : null,
  "is_void" : false,
  "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
  "merchant_identity" : "IDuqZpDw28f2KK6YuDk4jNLg",
  "messages" : [ ],
  "raw" : null,
  "security_code_verification" : "MATCHED",
  "source" : "PIe2YvpcjvoVJ6PzoRPBK137",
  "state" : "SUCCEEDED",
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "trace_id" : "fc6fde08-3615-4ab4-8838-9aeb209ec16f",
  "transfer" : null,
  "void_state" : "UNATTEMPTED",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AU4gmGGitJe2raohfb3VNeQ"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
    }
  }
}

Please note the Authorization will still need to be captured.

3D Secure Transfer

To perform a 3D secure payment with Transfer, create an Transfer and provide the 3d_secure_authentication data:

Copy
Copied
curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "3d_secure_authentication": {
	        "cardholder_authentication": "BwABBJQ1AgAAAAAgJDUCAAAAAAA=",
	        "electronic_commerce_indicator": "AUTHENTICATED",
	        "transaction_id": "EaOMucALHQqLAEGAgk"
	    },
	    "amount": 100,
	    "currency": "USD",
	    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
	    "source": "PIe2YvpcjvoVJ6PzoRPBK137",
	    "tags": {
	        "order_number": "21DFASJSAKAS"
	    }
	}'

A successful response returns 201 and the created Transfer.

Copy
Copied
{
  "id" : "TRbuQsQVVTXQrzGosZpksE9h",
  "created_at" : "2022-10-10T06:46:56.33Z",
  "updated_at" : "2022-10-10T06:46:56.88Z",
  "additional_buyer_charges" : null,
  "additional_healthcare_data" : null,
  "address_verification" : null,
  "amount" : 100,
  "amount_requested" : 100,
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "currency" : "USD",
  "destination" : null,
  "externally_funded" : "UNKNOWN",
  "failure_code" : null,
  "failure_message" : null,
  "fee" : 0,
  "idempotency_id" : null,
  "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
  "merchant_identity" : "IDuqZpDw28f2KK6YuDk4jNLg",
  "messages" : [ ],
  "raw" : null,
  "ready_to_settle_at" : null,
  "security_code_verification" : null,
  "source" : "PIe2YvpcjvoVJ6PzoRPBK137",
  "state" : "PENDING",
  "statement_descriptor" : "FNX*FINIX FLOWERS",
  "subtype" : "API",
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "trace_id" : "421d80c3-52f9-4e77-8a89-84eee5dc0c6d",
  "type" : "DEBIT",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRbuQsQVVTXQrzGosZpksE9h"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRbuQsQVVTXQrzGosZpksE9h/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRbuQsQVVTXQrzGosZpksE9h/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRbuQsQVVTXQrzGosZpksE9h/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRbuQsQVVTXQrzGosZpksE9h/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
    }
  }
}