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
object or null

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

object

Optional object detailing specific healthcare amounts.

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" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
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
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" "UNREFERENCED_REFUND" "MERCHANT_CREDIT_ADJUSTMENT" "MERCHANT_DEBIT_ADJUSTMENT" "CARD_PRESENT_AUTHORIZATION"
source
string

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

object

Key value pair for annotating custom meta data (e.g. order numbers).

object or null

The information required to create a 3D secure Authorization.

Responses
201

Single Authorization object

Response Schema: application/hal+json
id
string

The ID of the Authorization resource.

created_at
string <date-time>

Timestamp of when the object was created.

updated_at
string <date-time>

Timestamp of when the object was last updated.

3ds_redirect_url
string or null

The redirect URL used for 3DS transactions (if supported by the processor).

object or null

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

object

Optional object detailing specific healthcare amounts.

amount
integer >= 0

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

application
string

The ID of the Application resource the Authorization was created under.

object or null

Details needed to process card present transactions.

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.

currency
string

ISO 4217 3 letter currency code.

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
device
string or null

The ID of the activated device.

expires_at
string <date-time>

Authorization expiration time.

failure_code
string or null

The code of the failure so the decline can be handled programmatically. For more info on how to handle the failure, see Failure Codes.

failure_message
string or null

A human-readable description of why the transaction was declined. This will also include a suggestion on how to complete the payment.

idempotency_id
string or null

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

is_void
boolean

Details if the Authorization is void.

merchant_identity
string

The ID of the Merchant resource the Authorization was captured under.

messages
Array of strings

Message field that provides additional details. This field is typically null.

(Raw (object or null)) or (Raw (string or null))

Raw response from the processor.

source
string

ID of the Payment Instrument where funds get debited.

state
string

The state of the Authorization.

Enum: "CANCELED" "PENDING" "FAILED" "SUCCEEDED" "UNKNOWN"
object

Key value pair for annotating custom meta data (e.g. order numbers).

trace_id
string

Trace ID of the Authorization. The processor sends back the trace_id so you can track the authorization end-to-end.

transfer
string or null

The ID of the transfer resource that gets created when the Authorization moves to SUCCEEDED.

void_state
string

Details if the Authorization has been voided.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

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
{}

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.

created_at.gte
string

Filter where created_at is after the given date.

Example: created_at.gte=created_at.gte=2019-06-15
created_at.lte
string

Filter where created_at is before the given date.

Example: created_at.lte=created_at.lte=2019-06-15
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.

after_cursor
string

Return every resource created after the cursor value.

Responses
200

List of Authorization objects

Response Schema: application/hal+json
object

Details the page that's returned.

object

List of Authroization objects.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

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.json+api" \
  -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

Response Schema: application/hal+json
id
string

The ID of the Authorization resource.

created_at
string <date-time>

Timestamp of when the object was created.

updated_at
string <date-time>

Timestamp of when the object was last updated.

3ds_redirect_url
string or null

The redirect URL used for 3DS transactions (if supported by the processor).

object or null

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

object

Optional object detailing specific healthcare amounts.

amount
integer >= 0

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

application
string

The ID of the Application resource the Authorization was created under.

object or null

Details needed to process card present transactions.

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.

currency
string

ISO 4217 3 letter currency code.

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
device
string or null

The ID of the activated device.

expires_at
string <date-time>

Authorization expiration time.

failure_code
string or null

The code of the failure so the decline can be handled programmatically. For more info on how to handle the failure, see Failure Codes.

failure_message
string or null

A human-readable description of why the transaction was declined. This will also include a suggestion on how to complete the payment.

idempotency_id
string or null

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

is_void
boolean

Details if the Authorization is void.

merchant_identity
string

The ID of the Merchant resource the Authorization was captured under.

messages
Array of strings

Message field that provides additional details. This field is typically null.

(Raw (object or null)) or (Raw (string or null))

Raw response from the processor.

source
string

ID of the Payment Instrument where funds get debited.

state
string

The state of the Authorization.

Enum: "CANCELED" "PENDING" "FAILED" "SUCCEEDED" "UNKNOWN"
object

Key value pair for annotating custom meta data (e.g. order numbers).

trace_id
string

Trace ID of the Authorization. The processor sends back the trace_id so you can track the authorization end-to-end.

transfer
string or null

The ID of the transfer resource that gets created when the Authorization moves to SUCCEEDED.

void_state
string

Details if the Authorization has been voided.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

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.json+api" \
  -u USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041
Response samples
application/hal+json
{}

Capture an Authorization

If successfully captured, 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 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).

object

Key value pair for annotating custom meta data (e.g. order numbers).

void_me
boolean

Set to True to void the Authorization.

Responses
200

Single captured Authorization object

Response Schema: application/hal+json
id
string

The ID of the Authorization resource.

created_at
string <date-time>

Timestamp of when the object was created.

updated_at
string <date-time>

Timestamp of when the object was last updated.

3ds_redirect_url
string or null

The redirect URL used for 3DS transactions (if supported by the processor).

object or null

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

amount
integer >= 0

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

application
string

The ID of the Application resource the Authorization was created under.

object or null

Details needed to process card present transactions.

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.

currency
string

ISO 4217 3 letter currency code.

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
device
string or null

The ID of the activated device.

expires_at
string <date-time>

Authorization expiration time.

Array of objects or null
failure_code
string or null

The code of the failure so the decline can be handled programmatically. For more info on how to handle the failure, see Failure Codes.

failure_message
string or null

A human-readable description of why the transaction was declined. This will also include a suggestion on how to complete the payment.

idempotency_id
string or null

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

is_void
boolean

Details if the Authorization is void.

merchant_identity
string

The ID of the Merchant resource the Authorization was captured under.

messages
Array of strings

Message field that provides additional details. This field is typically null.

(Raw (object or null)) or (Raw (string or null))

Raw response from the processor.

source
string

ID of the Payment Instrument where funds get debited.

state
string

The state of the Transfer.

Enum: "CANCELED" "PENDING" "FAILED" "SUCCEEDED" "UNKNOWN"
object

Key value pair for annotating custom meta data (e.g. order numbers).

trace_id
string

Trace ID of the Authorization. The processor sends back the trace_id so you can track the authorization end-to-end.

transfer
string or null

The ID of the transfer resource that gets created when the Authorization moves to SUCCEEDED.

void_state
string

Details if the Authorization has been voided.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

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
{}