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
header Parameters
Accept
string
Default: application/hal+json
Finix-Version
string
Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01
Request Body schema: application/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 gets tied 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's 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.

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

The 3D secure information 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/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.

For details on how to query endpoints using the available parameters, see Query Parameters.

Request
query Parameters
amount
integer

Filter by an amount equal to the given value.

Example: amount=100
amount.gt
integer

Filter by an amount greater than.

Example: amount.gt=100
amount.gte
integer

Filter by an amount greater than or equal.

Example: amount.gte=100
amount.lt
integer

Filter by an amount less than.

Example: amount.lt=100
amount.lte
integer

Filter by an amount less than or equal.

Example: amount.lte=100
before_cursor
string

Return every resource created before the cursor value.

Example: before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
after_cursor
string

Return every resource created after the cursor value.

Example: after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
created_at.gte
string <date-time>

Filter where created_at is after the given date.

Example: created_at.gte=2022-09-27T11:21:23
created_at.lte
string <date-time>

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.

Example: idempotency_id=S6cVkY
limit
integer

The numbers of items to return.

Example: limit=10
tags.key
string

Filter by the key of a Tag.

Example: tags.key=test_key_100
tags.value
string

Filter by the value of a Tag.

Example: tags.value=test_val_100
state
any

Filter by transaction state.

Enum: "SUCCEEDED" "FAILED" "PENDING" "CANCELED"
Example: state=SUCCEEDED
updated_at.gte
string <date-time>

Filter where updated_at is after the given date.

Example: updated_at.gte=2022-09-27T11:21:23
updated_at.lte
string <date-time>

Filter where updated_at is before the given date.

Example: updated_at.lte=2023-01-21T10:17:22
trace_id
string

Filter by trace_id.

Example: trace_id=021fc4ed-f0a8-4932-820c-b22b542526f8
is_void
string

Filter by idempotency_id.

Example: is_void=S6cVkY
instrument_bin
string

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

Example: instrument_bin=411111
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 account number.

Example: instrument_account_last4=9444
instrument_brand_type
string

Filter by card brand.

Example: instrument_brand_type=VISA
merchant_identity_id
string

Filter by the Identity ID of the Merchant.

Example: merchant_identity_id=IDrtFLZWFYWzdYPw2DXFSodh
merchant_identity_name
string

Filter Transactions by name of the Identity.

Example: merchant_identity_name=John
instrument_name
string

Filter Transactions by the name of the Payment Instrument.

Example: instrument_name=Alice
instrument_type
string

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

Example: instrument_type=PAYMENT_CARD
merchant_id
string

Filter by Merchant ID.

Example: merchant_id=MUeDVrf2ahuKc9Eg5TeZugvs
merchant_mid
string

Filter by Merchant Identification Number (MID).

Example: merchant_mid=FNXrzKj8xCLBwB8FdxjfU9txe
instrument_card_last4
string

Filter by the payment card last 4 digits.

Example: instrument_card_last4=1111
merchant_processor_id
string

Filter by Processor ID.

header Parameters
Accept
string
Default: application/hal+json

Body Header

Finix-Version
string
Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01
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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/json
{}

Fetch an Authorization

Retrieve the details of a previously created Authorization.

Request
path Parameters
authorization_id
required
string

ID of Authorization to fetch.

Example: AUrEnGqdBi5oJs68ChNRcHJ3
header Parameters
Accept
string
Default: application/hal+json
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/AUsCN6f7qTLzxUD3Bp6iXQMQ" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/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 moves 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.

Example: AUrEnGqdBi5oJs68ChNRcHJ3
header Parameters
Accept
string
Default: application/hal+json
Finix-Version
string
Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01
Request Body schema: application/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.
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/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
header Parameters
Accept
string
Default: application/hal+json
Finix-Version
string
Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01
Request Body schema: application/json
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/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",
}