Making a 3D Secure Payment

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


3D Secure 2.0 lets you authenticate a transaction by having the cardholder verify the payment with their issuing bank. 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.

:::atention 3D Secure Vendors generate the values that get passed as part of 3d_secure_authentication and are needed 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/vnd.json+api" \
    -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_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/vnd.json+api" \
    -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_identity" : "IDuqZpDw28f2KK6YuDk4jNLg",
  "messages" : [ ],
  "raw" : null,
  "ready_to_settle_at" : null,
  "security_code_verification" : null,
  "source" : "PIe2YvpcjvoVJ6PzoRPBK137",
  "state" : "PENDING",
  "statement_descriptor" : "FNX*DUNDER MIFFLIN",
  "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"
    }
  }
}