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