Skip to content

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.
  • Include a fraud_session_id to assess the transaction for potential fraud. Reviewing transactions for fraud helps prevent potentially fraudulent activities by malicious actors.
Detecting Fraud

For more information on fraud detection, see: Creating an Authorization with Fraud Detection.

Request

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/authorizations \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "amount": 100,
    "currency": "USD",
    "merchant": "MUsVtN9pH65nGw61H7Nv8Apo",
    "source": "PIkxmtueemLD6dN9ZoWGHT44",
    "tags": {
      "order_number": "21DFASJSAKAS"
    }
  }'

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
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"
    }
  }
}
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

curl -i -X PUT \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/authorizations/AUg8unYpnWBEY1AdVUDkdQYJ \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "capture_amount": 100
  }'

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.

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"
    }
  }
}

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

curl -i -X PUT \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/authorizations/AUnubzehgQfqcvJpoxhqja7k \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "void_me": true
  }'

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.

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"
    }
  }
}

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