Sign in

v1

latestOpenAPI 3.0.22026-08-061303782.1 MB
Authorizations

Create an Authorization

Create an Authorization to process a transaction.

Related Guides: Creating and Capturing an Authorization, Level 2 and 3 Processing, POS Integration, Buyer Charges

post/authorizations

Headers

Finix-Versionstring
Example:2022-02-01

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

Content-Typestring
Example:application/json

The data type being sent in the request body must be application/json.

Request body

OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR

Example request

{
  "amount": 5000,
  "source": "PIxxxxxxxxxxxxxxxxxx"
}

Response

Response schema to a request to create a single Authorization object.

idstring

The ID of the Authorization resource.

created_atstring date-time

Timestamp of when the object was created.

updated_atstring date-time

Timestamp of when the object was last updated.

3ds_redirect_urlstring nullable

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

address_verificationstring nullable

Details the results of the Address Verification checks.

amountinteger

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

amount_requestedinteger

When default_partial_authorization_enabled is set to true, amount_requested indicates the amount the cardholder attempted to authorize.

applicationstring

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

currency'CAD' | 'USD'

ISO 4217 3-letter currency code.

created_via'CARD_PRESENT_SEMI_INTEGRATED_API' | 'CARD_PRESENT_STANDALONE' | 'CARD_PRESENT_STANDALONE_MANUAL_ENTRY' | 'CARD_PRESENT_IOS_APP' | 'CARD_PRESENT_IOS_APP_MANUAL_ENTRY' | 'CARD_PRESENT_IOS_D135_SDK' | 'CARD_PRESENT_ANDROID_APP' | 'CARD_PRESENT_ANDROID_APP_MANUAL_ENTRY' | 'CARD_PRESENT_ANDROID_D135_SDK' | 'CHECKOUT_FORM' | 'CYBERSOURCE' | 'PAYMENT_LINK' | 'PAYOUT_LINK' | 'PLUGIN_CHECKOUT_CHAMP' | 'PLUGIN_FYNTEK' | 'PLUGIN_GAMBLE_ID' | 'PLUGIN_GAMMA_SWEEP' | 'PLUGIN_HYPERSWITCH' | 'PLUGIN_PAYSIGHT' | 'PLUGIN_STICKYIO' | 'PLUGIN_TAGADA' | 'PLUGIN_WOO_COMMERCE' | 'SUBSCRIPTION' | 'UNKNOWN' | 'VIRTUAL_TERMINAL'

Gives more information about the product flow that was used to create the resource. Finix retains the right to add additional enums for this field without it being a breaking change.

devicestring nullable

The ID of the activated device.

expires_atstring date-time

Authorization expiration time.

failure_codestring nullable

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_messagestring nullable

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

identitystring

ID of the buyer 'Identity' to run the card present authorization. Finix tokenizes the card associated with the provided 'Identity' and processes the authorization, removing the need to create a blank buyer Identity.

idempotency_idstring nullable

Pass any randomly generated or internal ID to idempotently identify Transfers, Authorizations, or refund requests.

is_voidboolean

Whether the Authorization has been voided.

merchantstring

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

merchant_identitystring

The ID of the Identity resource used by the Merchant the Authorization was processed under.

messagesstring[] nullable

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

receipt_last_printed_atstring date-time nullable

Timestamp when the receipt was last printed.

security_code_verificationstring nullable

Details the results of the Security Code Verification che

sourcestring

ID of the Payment Instrument where funds get debited.

state'CANCELED' | 'PENDING' | 'FAILED' | 'SUCCEEDED' | 'UNKNOWN'

The state of the Authorization.

supplemental_feeinteger nullable

Amount in cents for which an additional fee will be created in addition to any fees created from the assigned fee profile.

tagsTags nullable

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. (For example, order_number: 25, item_type: produce, department: sales)
trace_idstring

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

transferstring nullable

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

void_state'UNATTEMPTED' | 'PENDING' | 'SUCCEEDED'

The state of the void attempt for the Authorization.

Example response

{
  "id": "AUxxxxxxxxxxxxxxxxxx",
  "amount": 5000,
  "device": "DVxxxxxxxxxxxxxxxxxx",
  "ip_address_details": {
    "ipv4": {
      "ip": "192.168.1.1"
    }
  },
  "merchant": "MUxxxxxxxxxxxxxxxxxxxxxx",
  "merchant_identity": "IDxxxxxxxxxxxxxxxxxxxxxx",
  "network_details": {
    "brand": "VISA"
  },
  "source": "PIxxxxxxxxxxxxxxxxxx",
  "transfer": "TRxxxxxxxxxxxxxxxxxx"
}