Creating and Capturing an Authorization

Learn how to authorize funds on a card before making a payment.

An Authorization (also known as a card hold) reserves a specific amount on a card; in other words confirming the buyer's Payment Instrument has enough funds to cover the transaction.

All Authorizations must be captured (i.e. debited) within seven days

Creating an Authorization

To create an Authorization:

  • Use the Payment Instrument#id that Finix returned as the Authorization#source .
  • Use the seller's Merchant#id as the Merchant of the Authorization .
  • Include a fraud_session_id to review the sale for fraud. Reviewing transactions for fraud helps stop any potentially fraudulent transactions performed by bad actors. For more information, see Create an Authorization with Fraud Detection.
Copy
Copied
curl https://finix.sandbox-payments-api.com/authorizations \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '{
    "amount": 100,
    "currency": "USD",
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "source": "PI3xXejPg2WSviCgEDThUVPP"
  }'

If the Authorization is successful, a response with state SUCCEEDED and a timestamp in expires_at gets returned.

Example Response

Copy
Copied
{
    "id": "AUg4BpSg6sfHEGjzqGuypP5c",
    "created_at": "2022-10-10T06:28:51.37Z",
    "updated_at": "2022-10-10T06:28:51.81Z",
    "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-17T06:28:51.37Z",
    "failure_code": null,
    "failure_message": null,
    "idempotency_id": null,
    "is_void": false,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg",
    "messages": [],
    "raw": null,
    "security_code_verification": "MATCHED",
    "source": "PI3xXejPg2WSviCgEDThUVPP",
    "state": "SUCCEEDED",
    "tags": {},
    "trace_id": "31c30f7c-c32f-4dc9-be4c-9e52fa9d94c5",
    "transfer": null,
    "void_state": "UNATTEMPTED",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/authorizations/AUg4BpSg6sfHEGjzqGuypP5c"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
        }
    }
}

The Authorization must be captured before expires_at passes or the funds will be released. If Authorization#transfer is null, the Authorization hasn't been captured yet.

Capturing an Authorization

Capture the succeeded Authorization when you're ready to debit the buyer's Payment Instrument. Capturing an Authorization initiates the movement of funds.

Copy
Copied
curl https://finix.sandbox-payments-api.com/authorizations/AUg4BpSg6sfHEGjzqGuypP5c \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X PUT \
  -d '{
    "capture_amount": 100
  }'

When an Authorization is captured, the Authorization#transfer gets updated with the ID of the Transfer resource that was created to debit funds for the Authorization.

Copy
Copied
{
    "id": "AUg4BpSg6sfHEGjzqGuypP5c",
    "created_at": "2022-10-10T06:28:51.37Z",
    "updated_at": "2022-10-10T06:29:27.31Z",
    "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-17T06:28:51.37Z",
    "failure_code": null,
    "failure_message": null,
    "idempotency_id": null,
    "is_void": false,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg",
    "messages": [],
    "raw": null,
    "security_code_verification": "MATCHED",
    "source": "PI3xXejPg2WSviCgEDThUVPP",
    "state": "SUCCEEDED",
    "tags": {},
    "trace_id": "31c30f7c-c32f-4dc9-be4c-9e52fa9d94c5",
    "transfer": "TRmGFuRw6k4FWCJiPBPn9frq",
    "void_state": "UNATTEMPTED",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/authorizations/AUg4BpSg6sfHEGjzqGuypP5c"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "transfer": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRmGFuRw6k4FWCJiPBPn9frq"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
        }
    }
}

By default, the Transfers get created are in a PENDING state, indicating that the capture request hasn't been submitted yet. Capture requests get submitted via batch request. Once submitted, the state of the Transfer will update to SUCCEEDED.

Query the ID in Authorization#transfer to view the Transfer resource and when it'll be ready to settle.

Void an Authorization

As opposed to Transfers which can only be reversed or refunded, Authorizations can be voided to release funds and stop a transaction from completing. For more details on how to void an Authorization, see Void an Authorization.

Copy
Copied
curl https://finix.sandbox-payments-api.com/authorizations/AU6Wnee6GqLAvX3GUAc3V9ay \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -X PUT \
    -d '
	{
	    "void_me": true
	}'

If an Authorization is voided, it can no longer be captured.

Example Response

Copy
Copied
{
    "id": "AU6Wnee6GqLAvX3GUAc3V9ay",
    "created_at": "2022-09-28T19:07:48.83Z",
    "updated_at": "2022-10-10T06:30:47.51Z",
    "3ds_redirect_url": null,
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
    "amount": 1000,
    "amount_requested": 1000,
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "currency": "USD",
    "expires_at": "2022-10-05T19:07:48.83Z",
    "failure_code": null,
    "failure_message": null,
    "idempotency_id": null,
    "is_void": true,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg",
    "messages": [],
    "raw": null,
    "security_code_verification": "MATCHED",
    "source": "PIe2YvpcjvoVJ6PzoRPBK137",
    "state": "SUCCEEDED",
    "tags": {
        "order_number": "21DFASJSAKAS"
    },
    "trace_id": "3b2a6cdb-9318-4444-8fce-8787a38f7fe0",
    "transfer": null,
    "void_state": "PENDING",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/authorizations/AU6Wnee6GqLAvX3GUAc3V9ay"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
        }
    }
}