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.
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:
{
"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:
|
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 |