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",
  • "_links": {}
}
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",
  • "_links": {}
}
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",
  • "_links": {}
}