Authorizations

An Authorization (also known as a card hold) reserves a specific amount on a card to be captured (i.e. debited) at a later date, usually within seven days.

When an Authorization is captured it produces a Transfer resource.

Related Guides: Creating and Capturing an Authorization, Level 2 and 3 Processing, In-Person Cloud Payments, Buyer Charges

Create an Authorization

Create an Authorization to process a transaction.

Related Guides: Creating and Capturing an Authorization, Level 2 and 3 Processing, In-Person Cloud Payments, Buyer Charges

Request
Request Body schema: application/hal+json
Any of:
object or null

Object detailing any Buyer Charges that got included in the Authorization.

object

Additional information about the purchase. Used for Level 2 and Level 3 Processing.

amount
required
integer <int64>

The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).

currency
required
string

ISO 4217 3 letter currency code.

Enum: "AED" "AFN" "ALL" "AMD" "ANG" … 174 more
device
string

The ID of the Device that the Authorization was created under.

fraud_session_id
string

The fraud_session_session ID you want to review for fraud. For more info, see Fraud Detection.

hsa_fsa_payment
boolean or null

Set to to true to process a payment using a Payment Instrument created from a health savings account (HSA) or flexible spending account (FSA).

idempotency_id
string or null

A randomly generated value that'll be associated with the request.

merchant
required
string

The ID of the Merchant that the Authorization was created under.

operation_key
string or null

Details the operation that'll be performed in the transaction (Card present transactions only) .

Enum: "PUSH_TO_CARD" "PULL_FROM_CARD" "CARD_PRESENT_DEBIT" "CARD_PRESENT_UNREFERENCED_REFUND" "SALE" … 4 more
security_code
string

The 3-4 digit security code for the card (i.e. CVV code). Include the CVV code of the card to include Card Verification Checks with the created Authorization.

source
required
string

The ID of the Payment Instrument that will be debited and performing the Authorization.

tags
object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

object or null

This information is required to create a 3D secure Authorization.

Responses
201

Single Authorization object

400

Error

401

Authentication information is missing or invalid

402

Payment Required

403

Forbidden

404

Object does not exist

406

Not Acceptable

422

Invalid field

post/authorizations
Request samples
Response samples
application/hal+json
{
  • "id": "AUvZbBaTJkFCbiAMrGtc66ko",
  • "created_at": "2022-10-11T02:27:39.10Z",
  • "updated_at": "2022-10-11T02:27:39.48Z",
  • "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-18T02:27:39.10Z",
  • "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": "e1a10287-4909-4aa7-9cb7-abd069a3b833",
  • "transfer": null,
  • "void_state": "UNATTEMPTED",
}

List Authorizations

Retrieve a list of Authorizations.

Request
query Parameters
amount
integer

Filter by an amount equal to the given value.

amount.gt
integer

Filter by an amount greater than.

amount.gte
integer

Filter by an amount greater than or equal.

amount.lt
integer

Filter by an amount less than.

amount.lte
integer

Filter by an amount less than or equal.

before_cursor
string

Return every resource created before the cursor value.

after_cursor
string

Return every resource created after the cursor value.

created_at.gte
string

Filter where created_at is after the given date.

Example: created_at.gte=2022-09-27T11:21:23
created_at.lte
string

Filter where created_at is before the given date.

Example: created_at.lte=2022-09-27T11:21:23
idempotency_id
string

Filter by idempotency_id.

limit
integer

The numbers of items to return.

Example: limit=10
sort
string

Specify key to be used for sorting the collection.

state
any

Filter by Transaction state.

Enum: "SUCCEEDED" "FAILED" "PENDING" "CANCELED"
updated_at.gte
string

Filter where updated_at is after the given date.

updated_at.lte
string

Filter where updated_at is before the given date.

trace_id
string

Filter by trace_id.

is_void
string

Filter by idempotency_id.

instrument_bin
string

Filter by Bank Identification Number (BIN). The BIN is the first 6 digits of the masked number.

instrument_account_last4
string

Filter Transactions by the last 4 digits of the bank account. The bank account last 4 are the last 4 digits of the masked number instrument_account_last4=9444 BIN.

instrument_brand_type
string

Filter by card brand. Available card brand types can be found in the drop-down.

merchant_identity_id
string

Filter by Identity ID.

merchant_identity_name
string

Filter Transactions by Identity name. The name is not case-sensitive.

instrument_name
string

Filter Transactions by Payment Instrument name.

instrument_type
string

Filter Transactions by Payment Instrument type. Available instrument types include: Bank Account or Payment Card.

merchant_id
string

Filter by Merchant ID.

merchant_mid
string

Filter by Merchant Identification Number (MID).

instrument_card_last4
string

Filter by the payment card last 4 digits.

merchant_processor_id
string

Filter by Processor ID.

type
string

Type of the Authorization.

tags.key
string

Filter by the key of a Tag.

tags.value
string

Filter by the value of a Tag.

Responses
200

List of Authorization objects

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/authorizations
Request samples
curl https://finix.sandbox-payments-api.com/authorizations \
  -H "Content-Type: application/vnd.api+json" \
  -u USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041
Response samples
application/hal+json
{}

Fetch an Authorization

Retrieve the details of a previously created Authorization.

Request
path Parameters
authorization_id
required
string

ID of Authorization to fetch.

Responses
200

Single Authorization object

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/authorizations/{authorization_id}
Request samples
curl https://finix.sandbox-payments-api.com/authorizations/AUcaGi9WKyKn2GwX3bNSpsXo \
  -H "Content-Type: application/vnd.api+json" \
  -u USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041
Response samples
application/hal+json
{
  • "id": "AUvZbBaTJkFCbiAMrGtc66ko",
  • "created_at": "2022-10-11T02:27:39.10Z",
  • "updated_at": "2022-10-11T02:27:39.48Z",
  • "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-18T02:27:39.10Z",
  • "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": "e1a10287-4909-4aa7-9cb7-abd069a3b833",
  • "transfer": null,
  • "void_state": "UNATTEMPTED",
}

Capture an Authorization

Use a PUT request to capture an Authorization. If captured successfully, the transfer field of the Authorization will contain the ID of the Transfer resource that'll move funds.

Related Guides: Creating and Capturing an Authorization, Level 2 and 3 Processing, In-Person Cloud Payments, Buyer Charges

Request
path Parameters
authorization_id
required
string

ID of Authorization to fetch.

Request Body schema: application/hal+json
object

Additional information about the purchase. Used for Level 2 and Level 3 Processing.

capture_amount
integer <int64>

The amount of the Authorization you would like to capture in cents. Must be less than or equal to the amount of the Authorization.

fee
integer <int64>

The minimum amount of the Authorization you'd like to collect as your fee in cents. Defaults to zero (must be less than or equal to the amount).

  • If the fees applied by the 'Fee Profile' are higher than the value passed in 'fee', 'fee' will not be applied and have no effect.
  • If the fees applied by the 'Fee Profile' are lower than the value passed in 'fee', an additional fee is be applied, in addition to the fees generated by the Fee Profile.
    • The additional fee is equal to the difference between the value passed in 'fee' and the fees generated by the Fee Profile.
tags
object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

void_me
boolean

Set to True to void the Authorization.

Responses
200

Single captured Authorization object

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

422

Invalid field

put/authorizations/{authorization_id}
Request samples
Response samples
application/hal+json
{}

Void an Authorization

Use a PUT request to void an Authorization. If voided successfully, funds get released and the transaction stops from completing. Additionally, voided Authorization can no longer be captured.

Related Guides: Creating and Capturing an Authorization, Level 2 and 3 Processing, In-Person Cloud Payments, Buyer Charges

Request
path Parameters
authorization_id_void_to
required
string
Request Body schema: application/hal+json
tags
object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

void_me
boolean

Set to True to void the Authorization.

Responses
200

Single captured Authorization object

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

422

Invalid field

put/authorizations/{authorization_id_void_to}
Request samples
Response samples
application/hal+json
{
  • "id": "AUeYYckKJTrBVu1j8FYLzJ3W",
  • "created_at": "2022-10-07T18:25:23.30Z",
  • "updated_at": "2022-10-07T18:29:59.38Z",
  • "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:25:23.30Z",
  • "failure_code": null,
  • "failure_message": null,
  • "idempotency_id": null,
  • "is_void": true,
  • "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
  • "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg",
  • "messages": [ ],
  • "raw": null,
  • "security_code_verification": "MATCHED",
  • "source": "PIe2YvpcjvoVJ6PzoRPBK137",
  • "state": "SUCCEEDED",
  • "tags": {
    • "order_number": "21DFASJSAKAS"
    },
  • "trace_id": "560e44af-5d22-4af2-801e-03d2dad69dc7",
  • "transfer": null,
  • "void_state": "SUCCEEDED",
}