auth and captures.md

Auth and Captures

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 the card, confirming that the buyer's payment method has sufficient 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 provided by Finix as the source.
Use the seller's Merchant ID as the merchant for the authorization.

Request

Example

Response

201 Created - Authorization Created A successful request returns a 201 Created status code, with the response body containing:

an expires_at timestamp for its expiration
the authorization's state as SUCCEEDED

Example Authorization

{
  "id": "AUfqb6x5gz8bcC4dAFoyvYo8",
  "created_at": "2025-10-27T15:50:16.97Z",
  "updated_at": "2025-10-27T15:50:16.97Z",
  "3ds_redirect_url": null,
  "additional_buyer_charges": {
    "convenience_amount": 10,
    "surcharge_amount": 0,
    "rent_surcharge_amount": 0
  },
  "additional_healthcare_data": {
    "clinic_amount": 50,
    "dental_amount": 200,
    "prescription_amount": 300,
    "vision_amount": 300
  },
  "additional_purchase_data": {
    "customer_reference_number": "321xyz",
    "customs_duty_amount": 10,
    "destination_country_code": null,
    "destination_postal_code": null,
    "discount_amount": 100,
    "invoice_reference_number": null,
    "order_date": null,
    "sales_tax": null,
    "sales_tax_finix_generated": 200,
    "ship_from_postal_code": null,
    "shipping_amount": 100,
    "tax_exempt": false,
    "item_data": [
      {
        "cost_per_unit": 500,
        "item_description": "printing paper",
        "item_discount_amount": 100,
        "merchant_product_code": "1149611",
        "quantity": 1,
        "amount_excluding_sales_tax": 400,
        "amount_including_sales_tax": 500,
        "unit_of_measure": "BX",
        "commodity_code": "175-62-20",
        "sales_tax_amount": 100,
        "sales_tax_rate": 0.25
      },
      {
        "cost_per_unit": 500,
        "item_description": "printing ink",
        "item_discount_amount": 0,
        "merchant_product_code": "2149612",
        "quantity": 1,
        "amount_excluding_sales_tax": 400,
        "amount_including_sales_tax": 500,
        "unit_of_measure": "CTN",
        "commodity_code": "207-72-54",
        "sales_tax_amount": 100,
        "sales_tax_rate": 0.25
      }
    ]
  },
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "amount": 100,
  "amount_requested": 100,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "currency": "USD",
  "expires_at": "2025-11-03T15:50:16.97Z",
  "failure_code": null,
  "failure_message": null,
  "idempotency_id": null,
  "ip_address_details": null,
  "is_void": false,
  "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
  "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H",
  "messages": [],
  "raw": null,
  "receipt_last_printed_at": null,
  "security_code_verification": "MATCHED",
  "source": "PIkxmtueemLD6dN9ZoWGHT44",
  "state": "SUCCEEDED",
  "supplemental_fee": null,
  "tags": {
    "order_number": "21DFASJSAKAS"
  },
  "trace_id": "92ef9b19-741a-4047-ac0a-b4e88b988743",
  "transfer": null,
  "void_state": "UNATTEMPTED",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/authorizations/AUfqb6x5gz8bcC4dAFoyvYo8"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H"
    }
  }
}

API Definition Authorization Expiration The authorization must be captured before the expires_at time passes, or the funds will be released. If transfer is null, the authorization has not 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.

Request

Example

Response

200 OK - Authorization Capture Submitted A successful request returns a 200 OK status code, and the response body contains a transfer property that corresponds to the ID of the Transfer resource created to debit funds.

Example Captured Authorization

{
  "id": "AUcmwpCN6yKJ2HGot6X4YSv7",
  "created_at": "2025-04-30T20:31:12.63Z",
  "updated_at": "2025-07-22T16:28:00.67Z",
  "3ds_redirect_url": null,
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_purchase_data": null,
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "amount": 100,
  "amount_requested": 100,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "currency": "USD",
  "expires_at": "2025-05-07T20:31:12.63Z",
  "failure_code": null,
  "failure_message": null,
  "idempotency_id": null,
  "is_void": false,
  "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
  "merchant_identity": "IDjvxGeXBLKH1V9YnWm1CS4n",
  "messages": [],
  "raw": null,
  "receipt_last_printed_at": null,
  "security_code_verification": "MATCHED",
  "source": "PIkxmtueemLD6dN9ZoWGHT44",
  "state": "SUCCEEDED",
  "supplemental_fee": null,
  "tags": {},
  "trace_id": "836faa82-15e4-4945-8923-94253464ddc4",
  "transfer": "TRfbdBWj2Ww6a2j7XfiqEoV4",
  "void_state": "UNATTEMPTED",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/authorizations/AUcmwpCN6yKJ2HGot6X4YSv7"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "transfer": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRfbdBWj2Ww6a2j7XfiqEoV4"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n"
    }
  }
}

API Definition

Next steps

Use the Fetch the Transfer endpoint with its ID to check the state of the Transfer when it will be ready to settle or to view its details.
Settle the Transfer (see Seller Payouts).

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.

Request

Example

Response

200 OK - Authorization Voided A successful request returns a 200 OK status code, and the response body indicates the void_state transitioned from UNATTEMPTED to PENDING. When the Authorization is voided, the void_state updates to SUCCEEDED.

Example Voided Authorization

{
  "id": "AUh4LG8REtmRBCxaSp85PMkr",
  "created_at": "2024-12-04T10:49:28.93Z",
  "updated_at": "2024-12-04T10:49:51.38Z",
  "3ds_redirect_url": null,
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_purchase_data": null,
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "amount": 100,
  "amount_requested": 100,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "currency": "USD",
  "expires_at": "2024-12-11T10:49:28.93Z",
  "failure_code": null,
  "failure_message": null,
  "idempotency_id": null,
  "is_void": false,
  "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
  "merchant_identity": "IDjvxGeXBLKH1V9YnWm1CS4n",
  "messages": [],
  "raw": null,
  "receipt_last_printed_at": null,
  "security_code_verification": "MATCHED",
  "source": "PIkxmtueemLD6dN9ZoWGHT44",
  "state": "SUCCEEDED",
  "tags": {
    "order_number": "21DFASJSAKAS"
  },
  "trace_id": "f9d829f3-6d84-41f1-a662-38ca99206af2",
  "transfer": "TRhzVLqF1TKjtMZsMJwA7P9j",
  "void_state": "PENDING",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/authorizations/AUh4LG8REtmRBCxaSp85PMkr"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "transfer": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRhzVLqF1TKjtMZsMJwA7P9j"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n"
    }
  }
}

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