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


 
Array of objects or null or null
    

  • An array used to detail how funds for the created Transfer will split and the amount Merchants receive.
    • 

  • The combined amounts under split_transfers must be equal to or less than the amount submitted in the Authorization.
    • 

  • For more information, see Split Transactions.
    • 



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