Deprecated API Reference

This API Reference is being deprecated. Please use the New API Reference.

Create an Authorization with 3D Secure

Authorizations can have two possible states, SUCCEEDED and FAILED. If the Authorization has succeeded, it must be captured before the expires_at or the funds will be released.

3D Secure 2.0 allows end-users to authenticate a transaction by having the cardholder authenticate with their issuing bank. By enabling 3D Secure on a transaction, you are shifting the liability of a chargeback from the merchant to the issuing bank. The integration requires a 3D Secure vendor to generate the values needed for 3d_secure_authentication.

Learn how to prevent duplicate authorizations by passing an idempotency ID in the payload.

warning

Authorizations on debit cards place a hold on funds in the cardholder's bank account and can lead to lower than expected balances and/or insufficient funds issues.

attention

If the transfer field of an Authorization is null, it has not been captured yet.

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"
	    }
	}'

Example Response:

Copy

Copied

{
  "id" : "AUk1vxrUDj1hSAASQ67BoyGH",
  "created_at" : "2022-10-07T18:03:39.36Z",
  "updated_at" : "2022-10-07T18:03:39.76Z",
  "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-14T18:03:39.36Z",
  "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" : "825bd009-13f3-4292-b8d3-b31f6eba4c52",
  "transfer" : null,
  "void_state" : "UNATTEMPTED",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUk1vxrUDj1hSAASQ67BoyGH"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/authorizations

Request Arguments

Field	Type	Description
`amount`	integer, required	The total amount that will be debited in cents (e.g. 100 cents to debit $1.00)
`currency`	string, required	3-letter ISO code designating the currency of the Transfers. (e.g. USD)
`fee`	integer, optional	The amount of the Transfer you would like to collect as your fee in cents. Defaults to zero (Must be less than or equal to the amount)
`idempotency_id`	string, optional	A randomly generated value that you want associated with the request
`merchant`	string, optional	Merchant ID of the merchant whom you're charging on behalf of
`source`	string, required	ID of the Payment Instrument that will be debited
`tags`	object, optional	Key value pair for annotating custom metadata (e.g. order numbers)

3d_secure_authentication-object Request Arguments

Field	Type	Description
`cardholder_authentication`	string, required	Provides evidence that the cardholder authentication occurred or that the merchant attempted authentication. This is unique for each authentication transaction.
`cardholder_ip_address`	integer, optional	Only required for American Express cards. Format is nnn.nnn.nnn.nnn
`electronic_commerce_indicator`	string, required	AUTHENTICATED: Approved by 3D Secure Vendor; ATTEMPTED: Issuer or cardholder does not support 3D Secure
`transaction_id`	string, optional	Only valid for Visa transactions