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