Deprecated API Reference

This API Reference is being deprecated. Please use the New API Reference.

Create an Authorization

authorizations have six states, two of which are expected: SUCCEEDED and FAILED. If an Authorization has succeeded, it must be captured before the date in expires_at passes. If the date in expires_at passes, the funds get released.

Learn how to prevent duplicate authorizations by passing an idempotency ID in the payload.

warning

Authorizations on debit cards place a hold on funds in the cardholder's bank account and can lead to lower than expected balances or issues involing insufficient funds.

attention

If the Transfer field of an Authorization is null, it has not been captured yet.

Copy

Copied

curl https://finix.sandbox-payments-api.com/authorizations \
    -H "Content-Type: application/vnd.json+api" \
    -H 'Finix-Version:2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "amount": 100,
	    "currency": "USD",
	    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
	    "source": "PIe2YvpcjvoVJ6PzoRPBK137",
	    "tags": {
	        "order_number": "21DFASJSAKAS"
	    }
	}'

Example Response:

Copy

Copied

{
  "id" : "AUeYYckKJTrBVu1j8FYLzJ3W",
  "created_at" : "2022-10-07T18:25:23.30Z",
  "updated_at" : "2022-10-07T18:25:23.44Z",
  "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" : false,
  "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" : "UNATTEMPTED",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUeYYckKJTrBVu1j8FYLzJ3W"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/authorizations

Request Arguments

Field	Type	Description
`amount`	integer, required	The amount of the authorization in cents
`currency`	string, required	3-letter ISO code designating the currency (e.g. USD)
`idempotency_id`	string, optional	A randomly generated value that you want associated with the request
`merchant_identity`	string, required	The ID of the `Identity` for the merchant that you are transacting on behalf of
`processor`	string, optional	If the Application has more than one processor association, it's required to pass the processor (e.g. DUMMY_V1)
`security_code`	string, optional	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`	string, required	The `Payment Instrument` that you will be performing the authorization
`tags`	object, optional	Key value pair for annotating custom metadata (e.g. order numbers)

Response

Field	Type	Description
`id`	string	The ID of the `Authorization` resource
`created_at`	string	Timestamp of when the object was created
`updated_at`	string	Timestamp of when the object was last updated
`3ds_redirect_url`	string	The redirect URL used for 3DS transactions (if supported by the processor)
`address_verification`	string	Details the results of the Address Verification checks.
`amount`	string	The total amount that will be debited in cents (e.g. 100 cents to debit $1.00)
`application`	object	The ID of the `Application` resource the `Authorization` was created under
`currency`	string	ISO 4217 3 letter currency code
`expires_at`	string	Authorization expiration time
`failure_code`	string	A `failure_code` is provided when a transaction is declined. For more information on how to handle `failure_codes` see Failure Codes
`failure_message`	string	Additional information about the `failure_code` and why the transaction was declined. For more information on how to handle `failure_codes` see Failure Codes
`idempotency_id`	string	A randomly generated value that'll be associated with the request
`is_void`	string	Details if the `Authorization` is void
`merchant_identity`	string	The ID of the `Identity` resource associated with the `Merchant`
`messages`	string	Message field that provides additional details. This field is typically null
`raw`	string	Raw response from the processor
`security_code_verification`	string	Details the results of the Security Code Verification checks.
`source`	string	ID of the `Payment Instrument` where funds get debited
`state`	string	The state of the `Authorization`. Available values include: CANCELED PENDING FAILED SUCCEEDED UNKNOWN
`tags`	string	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	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