Create an Authorization

Authorizations can have two possible states, 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 and/or insufficient funds issues.

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" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "source": "PIe2YvpcjvoVJ6PzoRPBK137",
	    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
	    "tags": {
	        "order_number": "21DFASJSAKAS"
	    },
	    "currency": "USD",
	    "amount": 100,
	    "processor": "DUMMY_V1"
	}'

Example Response:

Copy
Copied
{
  "id" : "AUeF44FtmytK6XD3JxjUt7HT",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2022-01-27T07:37:19.16Z",
  "updated_at" : "2022-01-27T07:37:19.28Z",
  "trace_id" : "b9e38593-da27-49e7-b948-f6c1d59d5e7e",
  "source" : "PIe2YvpcjvoVJ6PzoRPBK137",
  "merchant_identity" : "IDpYDM7J9n57q849o9E9yNrG",
  "3ds_redirect_url" : null,
  "is_void" : false,
  "void_state" : "UNATTEMPTED",
  "expires_at" : "2022-02-03T07:37:19.16Z",
  "idempotency_id" : null,
  "failure_code": null,
  "failure_message":
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUvAZfiEH7irXZf49P7o8P1r"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG"
    }
  }
}

HTTP Request

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

Request Arguments

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

Response

Field Type Description
id string The ID of the Authorization resource
application object The ID of the Application resource the Authorization was created under
amount string The total amount that will be debited in cents (e.g. 100 cents to debit $1.00)
tags string Key value pair for annotating custom meta data (e.g. order numbers)
state string The state of the Authorization. Available values include:
  • CANCELED
  • PENDING
  • FAILED
  • SUCCEEDED
  • UNKNOWN
currency string ISO 4217 3 letter currency code
transfer string The ID of the transfer resource that gets created when the Authorization moves to SUCCEEDED
messages string Message field that provides additional details. This field is typically null
raw string Raw response from the processor
created_at string Timestamp of when the object was created
updated_at string Timestamp of when the object was last updated
trace_id string Trace ID of the Authorization. The processor sends back the trace_id so you can track the authorization end-to-end
source string ID of the Payment Instrument where funds get debited
merchant_identity string The ID of the Identity resource associated with the Merchant
3ds_redirect_url string The redirect URL used for 3DS transactions (if supported by the processor)
is_void string Details if the Authorization is void
void_state string Details if the Authorization has been voided
expires_at string Authorization expiration time
idempotency_id string A randomly generated value that'll be associated with the request
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