# Level 2 / Level 3 Processing

Card payment processing has three levels: Level 1, Level 2, and Level 3. Level 2 and Level 3 processing allows eligible business-to-business (B2B) merchants to qualify for lower interchange rates by submitting additional purchase data alongside Visa and Mastercard transactions.

Level 2 / Level 3 Processing is available for:

- [Transfers](#create-a-sale-with-level-2-processing)
- [Authorizations](#create-an-authorization-with-level-2-processing)
- [Payment Links](/low-code-no-code/payment-links/quickstart-dashboard)


## Availability

- Available for merchants located in the **United States** processing **USD** transactions.
- Only available in **Live** environments. Not available in Sandbox.


## Eligibility

### Card networks that support Level 2 / Level 3 Processing

- **Mastercard**: Supports Level 2 and Level 3 processing.
- **Visa**: Supports Level 3 processing only.


| Network | Level 2 | Level 3 |
|  --- | --- | --- |
| Visa | ⚠️ Deprecated April 17, 2026 | Yes |
| Mastercard | Yes | Yes |


### Eligible Merchant types

Only business-to-business (B2B) merchants and government entities qualify for lower interchange rates. [The merchant must be enabled](#enable-level-2--level-3-processing) for Level 2 / Level 3 processing.

Corporate and purchase credit cards are eligible for Level 2 and Level 3 processing. Consumer cards are only eligible for Level 1 processing.

Ineligible Merchants
Some businesses are not eligible for Level 2 and Level 3 transaction processing.
For details, see our list of [ineligible Merchant Category Codes (MCC)](#ineligible-merchants).

### Data Quality

An eligible Merchant Category Code (MCC) alone does not guarantee interchange qualification. Card networks also evaluate the accuracy of submitted data. See Finix's [Data Quality](#data-quality-best-practices) best practices for Level 2 / Level 3 processing.

### Tax Exemption

Tax-exempt transactions are not eligible for Level 2. Tax-exempt transactions are eligible for Level 3 when you pass `tax_exempt: true` and omit `sales_tax`.

## Minimum Field Requirements

The table below summarizes the minimum fields required to qualify for Level 2 and Level 3 interchange rates. The card network and cardholder issuing bank ultimately determine whether a transaction qualifies.

| L2 or L3 Rates Eligibility | Level 2 | Level 3 |
|  --- | --- | --- |
| **Minimum Field Requirements** | - `customer_reference_number`
- `sales_tax`

 | - Everything in Level 2:
  - `shipping_amount`
  - `customs_duty_amount`
  - `discount_amount`
- Plus `item_data` for each line item:
  - `item_description`
  - `cost_per_unit`
  - `quantity`
  - `commodity_code`
  - `merchant_product_code`
  - `unit_of_measure`
  - `amount_excluding_sales_tax`
  - `amount_including_sales_tax`
  - `item_discount_amount`

 |


### Level 2 fields

| Field | API Field | Required | Description |
|  --- | --- | --- | --- |
| **Customer Reference Number** | `customer_reference_number` | Required | A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records. (max `17` characters) |
| **Sales Tax** | `sales_tax` | Required | The total tax amount for the transaction in cents. Must be greater than 0.1% of the transaction amount. For non-taxable transactions, set to `0` and set `tax_exempt` to `true`. |


### Level 3 fields

Everything in Level 2, plus:

| Field | API Field | Required | Description |
|  --- | --- | --- | --- |
| **Shipping Amount** | `shipping_amount` | Required | The costs related to shipping and handling in cents. Must be at least `0`. |
| **Customs Duty Amount** | `customs_duty_amount` | Required | The costs related to import or export duties in cents. Must be at least `0`. |
| **Discount Amount** | `discount_amount` | Required | The order-level discount amount in cents. Must be at least `0`. |
| **Tax Exempt** | `tax_exempt` | Optional | Set to `true` for tax-exempt purchases. |


Plus `item_data` fields for each line item:

| Field | API Field | Required | Description |
|  --- | --- | --- | --- |
| **Item Description** | `item_description` | Required | A short, human-readable description of the line item (max `25` characters). |
| **Cost per Item** | `cost_per_unit` | Required | The price per unit of the item purchased, in cents. |
| **Item Discount** | `item_discount_amount` | Required | The discount amount in cents applied to this individual line item. For an order-level discount, use `discount_amount`. |
| **Quantity** | `quantity` | Required | The number of units purchased. Must be greater than `0`. |
| **Unit of Measure** | `unit_of_measure` | Required | The unit of measure for the item (max `3` characters). |
| **Commodity Code** | `commodity_code` | Required | A numeric code identifying the product or service (`3`, `5`, `7`, or `11` digits; max `12` characters). |
| **Merchant Product Code** | `merchant_product_code` | Required | Your product/SKU code for the line item (max `12` characters). |
| **Amount Excluding Sales Tax** | `amount_excluding_sales_tax` | Required | Total cost of the line item excluding tax in cents (must be greater than `0`). |
| **Amount Including Sales Tax** | `amount_including_sales_tax` | Required | Total cost of the line item including tax in cents (must be greater than `0`). |


## Enable Level 2 / Level 3 Processing

Before a Merchant can process Level 2 or Level 3 transactions, send a PUT /merchants/{merchant_id} request to enable Level 2 / Level 3 processing.

### Request

Example
```shell cURL
curl -i -X PUT \
  -u '<username>:<password>' \
  https://finix.sandbox-payments-api.com/merchants/MUiV7ntxfY4eyJxp6E7cZvym \
  -H 'Content-Type: application/json' \
  -d '{
    "level_two_level_three_data_enabled": true
  }'
```

API Definition
```json
{
  "$ref": "#/components/schemas/updateMerchantEnableL2L3Processing",
  "components": {
    "schemas": {
      "tags": {
        "type": "object",
        "title": "tags",
        "additionalProperties": true,
        "description": "Include up to 50 `key: value` pairs to annotate requests with custom metadata.\n- Maximum character length for individual `keys` is 40.\n- Maximum character length for individual `values` is 500.\n(For example, `order_number: 25`, `item_type: produce`, `department: sales`)",
        "nullable": true
      },
      "updateMerchantEnableL2L3Processing": {
        "title": "Enable Level 2/3 Processing",
        "type": "object",
        "properties": {
          "level_two_level_three_data_enabled": {
            "type": "boolean",
            "description": "Set to **true** to enable the `Merchant` for Level 2 and Level 3 processing. Default value is **false**."
          },
          "tags": {
            "$ref": "#/components/schemas/tags"
          }
        }
      }
    }
  }
}
```

### Response

A successful request returns a `200 OK` status code and includes a Merchant resource with `level_two_level_three_data_enabled: true`.

Example
Merchant - Level 2/3 Processing Enabled
```json Merchant - Level 2/3 Processing Enabled
{
  "id": "MUiV7ntxfY4eyJxp6E7cZvym",
  "created_at": "2026-04-03T22:05:19.34Z",
  "updated_at": "2026-09-25T20:05:19.51Z",
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "card_cvv_required": false,
  "card_expiration_date_required": true,
  "card_network_details": null,
  "convenience_charges_enabled": true,
  "country": "USA",
  "creating_transfer_from_report_enabled": false,
  "currencies": [
    "USD"
  ],
  "default_partial_authorization_enabled": false,
  "disbursements_ach_pull_enabled": true,
  "disbursements_ach_push_enabled": true,
  "disbursements_card_pull_enabled": true,
  "disbursements_card_push_enabled": true,
  "disbursements_same_day_ach_pull_enabled": false,
  "disbursements_same_day_ach_push_enabled": false,
  "fee_ready_to_settle_upon": "PROCESSOR_WINDOW",
  "first_approved_at": "2026-04-03T22:06:04.00Z",
  "gateway": null,
  "gross_settlement_enabled": false,
  "identity": "IDa4fdEuy57uLT95prqoBDxx",
  "instant_payouts_card_push_enabled": false,
  "is_terminated": false,
  "level_two_level_three_data_enabled": true, // [!code highlight]
  "loan_repayment": null,
  "mcc": "4900",
  "merchant_name": "Finix Flowers",
  "merchant_profile": "MP6pzw61XykboCKVbMhCgYuk",
  "microdeposit_verification_required_buyer": false,
  "microdeposit_verification_required_sender": false,
  "mid": "FNXwXimxKRxzJ34EX4bAcv6q3",
  "onboarding_state": "APPROVED",
  "pending_refunds_strategy": "NONE",
  "processing_enabled": true,
  "processor": "DUMMY_V1",
  "processor_details": {
    "mid": "FNXwXimxKRxzJ34EX4bAcv6q3",
    "api_key": "secretValue"
  },
  "ready_to_settle_upon": "PROCESSOR_WINDOW",
  "ready_to_settle_upon_delay_alignment": "NONE",
  "refunds_disabled": false,
  "rent_surcharges_enabled": false,
  "settlement_enabled": true,
  "settlement_funding_identifier": "UNSET",
  "settlement_queue_mode": "MANUAL",
  "surcharges_enabled": false,
  "tags": {
    "key_2": "value_2"
  },
  "termination_details": null,
  "unreferenced_refund_card_present_enabled": false,
  "unreferenced_refund_manual_entry_enabled": false,
  "verification": "VIeDkhAdS91Cw4Hu324YR6Te",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/merchants/MUiV7ntxfY4eyJxp6E7cZvym"
    },
    "identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDa4fdEuy57uLT95prqoBDxx"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/merchants/MUiV7ntxfY4eyJxp6E7cZvym/verifications"
    },
    "merchant_profile": {
      "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MP6pzw61XykboCKVbMhCgYuk"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "verification": {
      "href": "https://finix.sandbox-payments-api.com/verifications/VIeDkhAdS91Cw4Hu324YR6Te"
    }
  }
}
```

API Definition
```json
{
  "$ref": "#/components/schemas/merchant",
  "components": {
    "schemas": {
      "id": {
        "type": "string",
        "minLength": 1,
        "description": "The ID of the resource."
      },
      "created_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was created."
      },
      "updated_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was last updated."
      },
      "country": {
        "type": "string",
        "enum": [
          "ABW",
          "AFG",
          "AGO",
          "AIA",
          "ALA",
          "ALB",
          "AND",
          "ARE",
          "ARG",
          "ARM",
          "ASM",
          "ATA",
          "ATF",
          "ATG",
          "AUS",
          "AUT",
          "AZE",
          "BDI",
          "BEL",
          "BEN",
          "BES",
          "BFA",
          "BGD",
          "BGR",
          "BHR",
          "BHS",
          "BIH",
          "BLM",
          "BLR",
          "BLZ",
          "BMU",
          "BOL",
          "BRA",
          "BRB",
          "BRN",
          "BTN",
          "BVT",
          "BWA",
          "CAF",
          "CAN",
          "CCK",
          "CHE",
          "CHL",
          "CHN",
          "CIV",
          "CMR",
          "COD",
          "COG",
          "COK",
          "COL",
          "COM",
          "CPV",
          "CRI",
          "CUB",
          "CUW",
          "CXR",
          "CYM",
          "CYP",
          "CZE",
          "DEU",
          "DJI",
          "DMA",
          "DNK",
          "DOM",
          "DZA",
          "ECU",
          "EGY",
          "ERI",
          "ESH",
          "ESP",
          "EST",
          "ETH",
          "FIN",
          "FJI",
          "FLK",
          "FRA",
          "FRO",
          "FSM",
          "GAB",
          "GBR",
          "GEO",
          "GGY",
          "GHA",
          "GIB",
          "GIN",
          "GLP",
          "GMB",
          "GNB",
          "GNQ",
          "GRC",
          "GRD",
          "GRL",
          "GTM",
          "GUF",
          "GUM",
          "GUY",
          "HKG",
          "HMD",
          "HND",
          "HRV",
          "HTI",
          "HUN",
          "IDN",
          "IMN",
          "IND",
          "IOT",
          "IRL",
          "IRN",
          "IRQ",
          "ISL",
          "ISR",
          "ITA",
          "JAM",
          "JEY",
          "JOR",
          "JPN",
          "KAZ",
          "KEN",
          "KGZ",
          "KHM",
          "KIR",
          "KNA",
          "KOR",
          "KWT",
          "LAO",
          "LBN",
          "LBR",
          "LBY",
          "LCA",
          "LIE",
          "LKA",
          "LSO",
          "LTU",
          "LUX",
          "LVA",
          "MAC",
          "MAF",
          "MAR",
          "MCO",
          "MDA",
          "MDG",
          "MDV",
          "MEX",
          "MHL",
          "MKD",
          "MLI",
          "MLT",
          "MMR",
          "MNE",
          "MNG",
          "MNP",
          "MRT",
          "MSR",
          "MTQ",
          "MUS",
          "MWI",
          "MYS",
          "MYT",
          "NAM",
          "NCL",
          "NER",
          "NFK",
          "NGA",
          "NIC",
          "NIU",
          "NLD",
          "NOR",
          "NPL",
          "NRU",
          "NZL",
          "OMN",
          "PAK",
          "PAN",
          "PCN",
          "PER",
          "PHL",
          "PLW",
          "PNG",
          "POL",
          "PRI",
          "PRK",
          "PRT",
          "PRY",
          "PSE",
          "PYF",
          "QAT",
          "REU",
          "ROU",
          "RUS",
          "RWA",
          "SAU",
          "SDN",
          "SEN",
          "SGP",
          "SGS",
          "SHN",
          "SJM",
          "SLB",
          "SLE",
          "SLV",
          "SMR",
          "SOM",
          "SPM",
          "SRB",
          "SSD",
          "STP",
          "SUR",
          "SVK",
          "SVN",
          "SWE",
          "SWZ",
          "SXM",
          "SYC",
          "SYR",
          "TCA",
          "TCD",
          "TGO",
          "THA",
          "TJK",
          "TKL",
          "TKM",
          "TLS",
          "TON",
          "TTO",
          "TUN",
          "TUR",
          "TUV",
          "TWN",
          "TZA",
          "UGA",
          "UKR",
          "UMI",
          "URY",
          "USA",
          "UZB",
          "VAT",
          "VCT",
          "VEN",
          "VGB",
          "VIR",
          "VNM",
          "VUT",
          "WLF",
          "WSM",
          "XKX",
          "YEM",
          "ZAF",
          "ZMB",
          "ZWE"
        ],
        "nullable": true
      },
      "currency": {
        "type": "string",
        "description": "ISO 4217 3-letter currency code.",
        "enum": [
          "CAD",
          "USD"
        ]
      },
      "refunds_disabled_merchant": {
        "type": "boolean",
        "default": false,
        "description": "A value of `true` disables refunds for the `Merchant`, including both referenced and unreferenced refunds."
      },
      "tags": {
        "type": "object",
        "title": "tags",
        "additionalProperties": true,
        "description": "Include up to 50 `key: value` pairs to annotate requests with custom metadata.\n- Maximum character length for individual `keys` is 40.\n- Maximum character length for individual `values` is 500.\n(For example, `order_number: 25`, `item_type: produce`, `department: sales`)",
        "nullable": true
      },
      "self": {
        "type": "object",
        "description": "Link to the resource that was used in the request.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "identity_link": {
        "type": "object",
        "description": "Link to the `Identity` the request was made under.",
        "properties": {
          "href": {
            "type": "string"
          }
        }
      },
      "verifications": {
        "type": "object",
        "description": "Link to the `Verification` the request was made under.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "merchant_profiles": {
        "type": "object",
        "description": "Link to the `merchant_profile` the request was made under.",
        "properties": {
          "href": {
            "type": "string"
          }
        }
      },
      "application_link": {
        "type": "object",
        "description": "Link to the `Application` the request was made under.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "merchant": {
        "title": "Merchant Schema",
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/id"
          },
          "created_at": {
            "$ref": "#/components/schemas/created_at"
          },
          "updated_at": {
            "$ref": "#/components/schemas/updated_at"
          },
          "application": {
            "type": "string",
            "minLength": 1,
            "description": "ID of the `Application` associated with the resource."
          },
          "card_cvv_required": {
            "type": "boolean",
            "description": "Set to `true` to require the card's CVV code."
          },
          "card_expiration_date_required": {
            "type": "boolean",
            "description": "Set to `true` to require the card's expiration date."
          },
          "card_network_details": {
            "type": "object",
            "nullable": true
          },
          "convenience_charges_enabled": {
            "type": "boolean",
            "description": "Set to `true` if you want to enable the `Merchant` to accept convenience fees and/or service fees."
          },
          "country": {
            "description": "The `Merchant`'s country.",
            "allOf": [
              {
                "$ref": "#/components/schemas/country"
              }
            ]
          },
          "creating_transfer_from_report_enabled": {
            "type": "boolean",
            "description": "Set to `true` to automatically create `Transfers` once settlement reports get generated."
          },
          "currencies": {
            "type": "array",
            "description": "ISO 4217 3-letter currency code.",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/currency"
            }
          },
          "default_partial_authorization_enabled": {
            "type": "boolean",
            "default": false,
            "description": "- Set to **true** if you want to enable partial authorizations for a specific `Merchant`.\n- Partial authorizations enable the `Merchant` to collect a portion of the amount if the cardholder doesn't have the funds to cover the entire amount on their card.\n"
          },
          "disbursements_ach_pull_enabled": {
            "type": "boolean",
            "description": "Indicates whether standard ACH pull disbursements (debits) are enabled."
          },
          "disbursements_ach_push_enabled": {
            "type": "boolean",
            "description": "Indicates whether standard ACH push disbursements (credits) are enabled."
          },
          "disbursements_card_pull_enabled": {
            "type": "boolean",
            "description": "Indicates whether card pull disbursements are enabled."
          },
          "disbursements_card_push_enabled": {
            "type": "boolean",
            "description": "Indicates whether card push disbursements are enabled."
          },
          "disbursements_same_day_ach_pull_enabled": {
            "type": "boolean",
            "description": "Indicates whether same-day ACH pull disbursements (debits) are enabled, allowing funds to be withdrawn from an account via same-day ACH transfer."
          },
          "disbursements_same_day_ach_push_enabled": {
            "type": "boolean",
            "description": "Indicates whether same-day ACH push disbursements (credits) are enabled, allowing funds to be sent to an account via same-day ACH transfer."
          },
          "fee_ready_to_settle_upon": {
            "type": "string",
            "description": "Details how the `Merchant` settles fees.",
            "enum": [
              "RECONCILIATION",
              "SUCCESSFUL_CAPTURE",
              "PROCESSOR_WINDOW",
              "CONFIGURABLE_WINDOW"
            ]
          },
          "first_approved_at": {
            "type": "string",
            "format": "date-time",
            "description": "This field shows the timestamp when the `Merchant` was first approved. If the `Merchant` has not been approved yet, the value is `null`.\n",
            "nullable": true
          },
          "gateway": {
            "type": "string",
            "description": "The `Merchant` payment gateway.",
            "nullable": true
          },
          "gross_settlement_enabled": {
            "type": "boolean",
            "description": "Set to `true` to enable gross settlements."
          },
          "identity": {
            "type": "string",
            "description": "The ID of the `Identity` resource associated with the `Merchant`."
          },
          "instant_payouts_card_push_enabled": {
            "type": "boolean",
            "description": "Set to `true` if you want to allow the merchant to be enabled for settlement instant payouts.",
            "default": false
          },
          "is_terminated": {
            "type": "boolean",
            "description": "Set to `true` to terminate the `Merchant`. A merchant can only be terminated if its current `onboarding_state` is `APPROVED`."
          },
          "level_two_level_three_data_enabled": {
            "type": "boolean",
            "description": "Set to `true` to enable the `Merchant` for Level 2 and Level 3 processing. Default value is `false`."
          },
          "loan_repayment": {
            "type": "boolean",
            "default": false,
            "nullable": true,
            "description": "Whether the merchant is able to support loan repayment on the card networks.\n"
          },
          "mcc": {
            "type": "string",
            "description": "The Merchant Category Code ([MCC](http://www.dm.usda.gov/procurement/card/card\\_x/mcc.pdf)) that this merchant will be classified under. For a list of approved MCCs, see [Approved Merchant Category Codes.](/guides/managing-operations/security-compliance/approved-merchant-category-codes)",
            "nullable": true
          },
          "merchant_name": {
            "type": "string",
            "description": "The legal name saved in the `Merchant` resource."
          },
          "merchant_profile": {
            "type": "string",
            "description": "Details if a merchant's info was submitted to third-party processors for provisioning."
          },
          "microdeposit_verification_required_buyer": {
            "type": "boolean",
            "description": "Whether microdeposit verification is required for buyers."
          },
          "microdeposit_verification_required_sender": {
            "type": "boolean",
            "description": "Whether microdeposit verification is required for senders."
          },
          "microdeposit_verification_send_email_enabled": {
            "type": "boolean",
            "description": "Whether Finix emails the bank account owner when a microdeposit verification is created."
          },
          "mid": {
            "type": "string",
            "description": "MID of the `Merchant`.",
            "nullable": true
          },
          "onboarding_state": {
            "type": "string",
            "enum": [
              "APPROVED",
              "PROVISIONING",
              "REJECTED",
              "UPDATE_REQUESTED"
            ],
            "description": "Details the state of the `Merchant's` onboarding."
          },
          "processing_enabled": {
            "type": "boolean",
            "description": "Details if transaction processing is enabled for the `Merchant`. `ROLE_PARTNER` can only set this value to `false`."
          },
          "processor": {
            "type": "string",
            "description": "Name of the transaction processor.",
            "enum": [
              "FINIX_V1",
              "DUMMY_V1"
            ]
          },
          "processor_details": {
            "type": "object",
            "description": "Additional details specific to the processor.",
            "properties": {
              "mid": {
                "type": "string"
              },
              "api_key": {
                "type": "string"
              }
            }
          },
          "pending_refunds_strategy": {
            "type": "string",
            "description": "The strategy used to hold refunds for this `Merchant`. Refunds stay in `PENDING` until the merchant's settlement balance covers them. For more information, see [Pending refunds](/guides/after-the-payment/refunds/pending-refunds).\n\n`ROLE_PARTNER` credentials can set the following strategies:\n- `SEVEN_DAY_DELAYED_ADJUSTMENT`: Refunds are held in `PENDING` for up to 7 days to be covered by settlement funds. After 7 days, Finix debits the merchant's bank account to cover the refund.\n- `SAME_DAY_ADJUSTMENT`: Finix issues a debit adjustment near settlement close if the settlement can't cover the refund.\n",
            "enum": [
              "NONE",
              "SEVEN_DAY_DELAYED_ADJUSTMENT",
              "SAME_DAY_ADJUSTMENT"
            ],
            "nullable": true
          },
          "ready_to_settle_upon": {
            "type": "string",
            "description": "Details how transactions captured by the `Merchant` are settled.",
            "enum": [
              "RECONCILIATION",
              "SUCCESSFUL_CAPTURE",
              "PROCESSOR_WINDOW",
              "CONFIGURABLE_WINDOW"
            ]
          },
          "ready_to_settle_upon_delay_alignment": {
            "type": "string",
            "description": "Indicates whether transaction settlement should be delayed to synchronize the timing of all transactions, including both card and ACH, ensuring they are settled together.\n\nPossible values include:\n\n- `ACH` - Align all transactions to match the timing of ACH settlements, so card transactions settle at the same speed as ACH transactions.\n- `NONE` - Default behavior where card transactions settle the next day (T+1) and ACH transactions settle two days later (T+2).\n",
            "enum": [
              "ACH",
              "NONE"
            ]
          },
          "refunds_disabled": {
            "$ref": "#/components/schemas/refunds_disabled_merchant"
          },
          "rent_surcharges_enabled": {
            "type": "boolean",
            "description": "Set to `true` if you want to enable a `Merchant` to accept rent charges."
          },
          "settlement_enabled": {
            "type": "boolean",
            "description": "Details if settlement approvals are enabled for the `Merchant`. `ROLE_PARTNER` can only set this value to false."
          },
          "settlement_funding_identifier": {
            "type": "string",
            "description": "Includes additional information (like the MID or `Merchant` name) when submitting funding `Transfers` to processors.\n- `UNSET`: No additional details get provided to the processor.\n- `MID_AND_DATE`: The `MID` of the `Merchant` and the date the funding `Transfer` was submitted (Date is in UTC). e.g `MID:12345678-20220225`\n- `MID_AND_MERCHANT_NAME`: The `MID` of the `Merchant` and the `Merchant#name` (white spaces will be removed). e.g. `MID:12345678-NameOfMerchant`\n\nThese details appear alongside the seller's payout in their bank account as a description of the deposit.",
            "enum": [
              "UNSET",
              "MID_AND_DATE",
              "MID_AND_MERCHANT_NAME"
            ],
            "default": "UNSET"
          },
          "settlement_queue_mode": {
            "type": "string",
            "description": "If `settlement_queue_mode` is set to `MANUAL`, Finix will automatically place all transactions (Sales, Fees, Refunds, and ACH Returns) into a settlement queue that you can manage. Each transaction will have a `Settlement Queue Entry`.\n\nWhen a `Settlement Queue Entry` is created, it will not be placed into `Settlement` until the `Settlement Queue Entry` is explicitly released.\n\nNote: We require the release of all settlement queue entries within 30 days of creation.\n",
            "enum": [
              "UNSET",
              "MANUAL"
            ]
          },
          "surcharges_enabled": {
            "type": "boolean",
            "default": false,
            "description": "Set to `true` if you want to enable a `Merchant` to accept surcharge fees. For more details, see [Buyer Charges](/guides/online-payments/payment-features/buyer-charges)."
          },
          "tags": {
            "$ref": "#/components/schemas/tags"
          },
          "termination_details": {
            "type": "object",
            "nullable": true,
            "properties": {
              "terminated_at": {
                "type": "string",
                "title": "CreatedAt",
                "format": "date-time",
                "example": "2024-09-16T13:11:36.72Z",
                "description": "Timestamp indicating when the termination occurred."
              },
              "reason": {
                "type": "string",
                "description": "The reason for termination. Finix reserves the right to return enums that are not listed here.",
                "enum": [
                  "CHURNED",
                  "COMPLIANCE_VIOLATION",
                  "EXCESSIVE_ACH_RETURNS",
                  "EXCESSIVE_CHARGEBACKS",
                  "FRAUD",
                  "IDENTITY_THEFT",
                  "ILLEGAL_TRANSACTIONS",
                  "INSOLVENCY",
                  "OTHER",
                  "PCI_VIOLATION",
                  "PROCESSOR_MIGRATION",
                  "SUSPECTED_FRAUD",
                  "UNSUPPORTED_BUSINESS_TYPE",
                  "UNUSUAL_ACTIVITY",
                  "VIOLATED_MERCHANT_TERMS_OF_SERVICE"
                ]
              },
              "description": {
                "type": "string",
                "description": "An explanation that provides context for the termination.",
                "maxLength": 1000
              },
              "terminated_by": {
                "type": "string",
                "description": "The role that initiated the termination. If the API key belongs to the `USER` role, the following values will be returned:\n  - If the role is `ROLE_PLATFORM`, it will return `PLATFORM_USER`.\n  - If the role is `ROLE_PARTNER`, it will return `PARTNER_USER`.\n",
                "enum": [
                  "PLATFORM_USER",
                  "PARTNER_USER"
                ]
              },
              "terminated_by_user_id": {
                "type": "string",
                "description": "The `User` ID of the user who initiated the termination of the `Merchant` account."
              }
            }
          },
          "unreferenced_refund_card_present_enabled": {
            "type": "boolean",
            "description": "Indicates if the merchant is allowed to process unreferenced refunds initiated through card-present transactions on Finix terminals."
          },
          "unreferenced_refund_manual_entry_enabled": {
            "type": "boolean",
            "default": false,
            "description": "Indicates if merchant is allowed to process unreferenced refunds initiated through manual card entry on Finix terminals."
          },
          "verification": {
            "type": "string",
            "description": "ID of the `Verification` that was submitted to verify the `Merchant`."
          },
          "_links": {
            "type": "object",
            "description": "For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these `_links` to make your follow-up requests and quickly access relevant IDs.",
            "properties": {
              "self": {
                "$ref": "#/components/schemas/self"
              },
              "identity": {
                "$ref": "#/components/schemas/identity_link"
              },
              "verifications": {
                "$ref": "#/components/schemas/verifications"
              },
              "merchant_profile": {
                "$ref": "#/components/schemas/merchant_profiles"
              },
              "merchant_profiles": {
                "$ref": "#/components/schemas/merchant_profiles"
              },
              "verification": {
                "$ref": "#/components/schemas/verifications"
              },
              "application": {
                "$ref": "#/components/schemas/application_link"
              }
            }
          }
        }
      }
    }
  }
}
```

Once `level_two_level_three_data_enabled` is updated to `true`, the Merchant resource can process [Level 2 and Level 3 Transfers and Authorizations](#create-a-sale-with-level-2-processing).

- There are no changes in the post-payment experience (reversals, refunds, settlements, etc.) when processing Level 2 or Level 3 transactions.
- The [fields noted as required](#minimum-field-requirements) are the minimum needed for Level 2 or Level 3 interchange rates. There's no additional benefit in passing every available field for a given level.
- The sales tax amount must be greater than 0.1% of the transaction amount.
- For tax-exempt transactions, pass `tax_exempt` as `true` and omit `sales_tax`.


## Create a Sale with Level 2 processing

Send a POST /transfers request and include the required fields for Level 2 processing.

### Level 2 Fields

Include the following fields within the `additional_purchase_data` object:

| Field | API Field | Type | Description |
|  --- | --- | --- | --- |
| **Customer Reference Number** | `customer_reference_number` | *string*, **required** | A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records. (max `17` characters) |
| **Sales Tax** | `sales_tax` | *integer*, **required** | Total aggregate tax amount in cents for the entire purchase. Field is automatically calculated if you pass in the itemized tax amounts. For non-taxable transactions either set `sales_tax` to `0` or omit from payload and also set `tax_exempt` to `true`.` |


### Request

```shell
curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/transfers \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "additional_purchase_data": {
      "customer_reference_number": "PO-2024-3842",
      "sales_tax": 200
    },
    "amount": 10000,
    "currency": "USD",
    "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
    "source": "PIs3rzrjP9orEjBwtJjhxEjL",
    "tags": {
      "order_id": "ORD-123"
    }
  }'
```

### Response

A successful request returns a `201 Created` status code and includes a Transfer resource with Level 2 processing details:

Example
Transfer - Level 2 Processing
```json Transfer - Level 2 Processing
{
  "id": "TRhxcLi5xeLc6S6cw15RFFFe",
  "created_at": "2026-09-25T20:05:58.23Z",
  "updated_at": "2026-09-25T20:05:58.23Z",
  "3d_secure_session": null,
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_lodging_data": null,
  "additional_motor_vehicle_rental_data": null,
  "additional_purchase_data": {
    "customer_reference_number": "PO-2024-3842", // [!code highlight]
    "customs_duty_amount": null,
    "destination_country_code": null,
    "destination_postal_code": null,
    "discount_amount": null,
    "invoice_reference_number": null,
    "order_date": null,
    "sales_tax": 200, // [!code highlight]
    "sales_tax_finix_generated": null,
    "ship_from_postal_code": null,
    "shipping_amount": null,
    "tax_exempt": false,
    "item_data": []
  },
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "amount": 10000,
  "amount_requested": 10000,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_via": "UNKNOWN",
  "currency": "USD",
  "destination": null,
  "externally_funded": "UNKNOWN",
  "failure_code": null,
  "failure_message": null,
  "fee": 0,
  "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj",
  "idempotency_id": null,
  "ip_address_details": null,
  "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
  "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H",
  "messages": [],
  "network_details": {
    "brand": "MASTERCARD",
    "authorization_code": "179463",
    "acquirer_reference_number": "79996936117050932176855"
  },
  "operation_key": "CARD_NOT_PRESENT_SALE",
  "parent_transfer": null,
  "parent_transfer_trace_id": null,
  "processed_at": "2026-09-25T20:05:58.57Z",
  "raw": null,
  "ready_to_settle_at": "2026-09-26T20:05:58.23Z",
  "receipt_last_printed_at": null,
  "security_code_verification": "MATCHED",
  "source": "PIs3rzrjP9orEjBwtJjhxEjL",
  "split_transfers": [],
  "state": "SUCCEEDED",
  "statement_descriptor": "FLX*FINIX FLOWERS",
  "subtype": "API",
  "supplemental_fee": null,
  "tags": {
    "order_id": "ORD-123"
  },
  "third_party_details": null,
  "tip_amount": null,
  "trace_id": "4c050b39-9589-4253-b3b6-f71428629e22",
  "type": "DEBIT",
  "_links": {
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "self": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRhxcLi5xeLc6S6cw15RFFFe"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRhxcLi5xeLc6S6cw15RFFFe/payment_instruments"
    },
    "reversals": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRhxcLi5xeLc6S6cw15RFFFe/reversals"
    },
    "fees": {
      "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRhxcLi5xeLc6S6cw15RFFFe"
    },
    "disputes": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRhxcLi5xeLc6S6cw15RFFFe/disputes"
    },
    "source": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIs3rzrjP9orEjBwtJjhxEjL"
    },
    "fee_profile": {
      "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj"
    }
  }
}
```

API Definition
```json
{
  "$ref": "#/components/schemas/transfer",
  "components": {
    "schemas": {
      "id": {
        "type": "string",
        "minLength": 1,
        "description": "The ID of the resource."
      },
      "created_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was created."
      },
      "updated_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was last updated."
      },
      "additional_buyer_charges": {
        "type": "object",
        "description": "Additional charges will be incurred by the buyer.\n\nThe following rules apply:\n\n- The `Merchant` must be enabled to charge these surcharges by setting the appropriate flags for each applicable surcharge to `true` using the PUT `/merchants` endpoint.\n- Only _one_ of the following charges can be applied during creation.\n",
        "nullable": true,
        "properties": {
          "convenience_amount": {
            "type": "integer",
            "description": "A convenience fee to charge the buyer for the transaction. This object property is mutually exclusive.",
            "nullable": true
          },
          "rent_surcharge_amount": {
            "type": "integer",
            "description": "A rent surcharge to charge the buyer for the transaction. This object property is mutually exclusive.",
            "nullable": true
          },
          "surcharge_amount": {
            "type": "integer",
            "description": "A surcharge amount to charge the buyer for the transaction. This object property is mutually exclusive.",
            "nullable": true
          }
        }
      },
      "additional_healthcare_data": {
        "type": "object",
        "nullable": true,
        "properties": {
          "clinic_amount": {
            "type": "integer",
            "description": "A clinic or other qualified medical amount for the transaction.",
            "nullable": true
          },
          "dental_amount": {
            "type": "integer",
            "description": "The dental amount for the transaction.",
            "nullable": true
          },
          "prescription_amount": {
            "type": "integer",
            "description": "The prescription/RX amount for the transaction.",
            "nullable": true
          },
          "vision_amount": {
            "type": "integer",
            "description": "The vision/optical amount for the transaction.",
            "nullable": true
          }
        }
      },
      "additional_lodging_data": {
        "type": "object",
        "nullable": true,
        "description": "Contains lodging-specific fields for `Authorization` and `Transfer` requests. Optional for lodging MCC transactions (MCC 3501–3999, 7011). Returns `null` for all other transactions.",
        "properties": {
          "check_in_date": {
            "type": "object",
            "nullable": true,
            "description": "The guest's scheduled arrival date.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the check-in date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the check-in date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the check-in date."
              }
            }
          },
          "check_out_date": {
            "type": "object",
            "nullable": true,
            "description": "The guest's scheduled departure date. Must represent a date on or after `check_in_date`.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the check-out date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the check-out date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the check-out date."
              }
            }
          },
          "customer_service_phone": {
            "type": "string",
            "nullable": true,
            "description": "The phone number guests can call for support or inquiries related to their stay."
          },
          "extra_charge_details": {
            "type": "object",
            "nullable": true,
            "description": "Additional charges billed beyond the room rate. Each field represents a specific charge type, in cents.",
            "properties": {
              "restaurant_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "mini_bar_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "laundry_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "other_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "phone_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "gift_shop_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              }
            }
          },
          "hotel_agreement_number": {
            "type": "string",
            "nullable": true,
            "description": "The folio or agreement number associated with the reservation. Max 12 characters; longer values are truncated."
          },
          "is_advance_deposit": {
            "type": "boolean",
            "nullable": true,
            "default": false,
            "description": "Indicates whether the lodging charge is an advance deposit."
          },
          "is_no_show": {
            "type": "boolean",
            "nullable": true,
            "default": false,
            "description": "Set to `true` if the cardholder is being billed for a reserved room that was not occupied."
          },
          "number_of_nights": {
            "type": "integer",
            "nullable": true,
            "description": "The total number of nights for the lodging stay."
          },
          "property_phone": {
            "type": "string",
            "nullable": true,
            "description": "The direct phone number of the lodging property."
          },
          "room_rate": {
            "type": "string",
            "nullable": true,
            "description": "The nightly room rate, in cents."
          },
          "room_tax": {
            "type": "string",
            "nullable": true,
            "description": "The tax amount applied to the room rate, in cents."
          }
        }
      },
      "country": {
        "type": "string",
        "enum": [
          "ABW",
          "AFG",
          "AGO",
          "AIA",
          "ALA",
          "ALB",
          "AND",
          "ARE",
          "ARG",
          "ARM",
          "ASM",
          "ATA",
          "ATF",
          "ATG",
          "AUS",
          "AUT",
          "AZE",
          "BDI",
          "BEL",
          "BEN",
          "BES",
          "BFA",
          "BGD",
          "BGR",
          "BHR",
          "BHS",
          "BIH",
          "BLM",
          "BLR",
          "BLZ",
          "BMU",
          "BOL",
          "BRA",
          "BRB",
          "BRN",
          "BTN",
          "BVT",
          "BWA",
          "CAF",
          "CAN",
          "CCK",
          "CHE",
          "CHL",
          "CHN",
          "CIV",
          "CMR",
          "COD",
          "COG",
          "COK",
          "COL",
          "COM",
          "CPV",
          "CRI",
          "CUB",
          "CUW",
          "CXR",
          "CYM",
          "CYP",
          "CZE",
          "DEU",
          "DJI",
          "DMA",
          "DNK",
          "DOM",
          "DZA",
          "ECU",
          "EGY",
          "ERI",
          "ESH",
          "ESP",
          "EST",
          "ETH",
          "FIN",
          "FJI",
          "FLK",
          "FRA",
          "FRO",
          "FSM",
          "GAB",
          "GBR",
          "GEO",
          "GGY",
          "GHA",
          "GIB",
          "GIN",
          "GLP",
          "GMB",
          "GNB",
          "GNQ",
          "GRC",
          "GRD",
          "GRL",
          "GTM",
          "GUF",
          "GUM",
          "GUY",
          "HKG",
          "HMD",
          "HND",
          "HRV",
          "HTI",
          "HUN",
          "IDN",
          "IMN",
          "IND",
          "IOT",
          "IRL",
          "IRN",
          "IRQ",
          "ISL",
          "ISR",
          "ITA",
          "JAM",
          "JEY",
          "JOR",
          "JPN",
          "KAZ",
          "KEN",
          "KGZ",
          "KHM",
          "KIR",
          "KNA",
          "KOR",
          "KWT",
          "LAO",
          "LBN",
          "LBR",
          "LBY",
          "LCA",
          "LIE",
          "LKA",
          "LSO",
          "LTU",
          "LUX",
          "LVA",
          "MAC",
          "MAF",
          "MAR",
          "MCO",
          "MDA",
          "MDG",
          "MDV",
          "MEX",
          "MHL",
          "MKD",
          "MLI",
          "MLT",
          "MMR",
          "MNE",
          "MNG",
          "MNP",
          "MRT",
          "MSR",
          "MTQ",
          "MUS",
          "MWI",
          "MYS",
          "MYT",
          "NAM",
          "NCL",
          "NER",
          "NFK",
          "NGA",
          "NIC",
          "NIU",
          "NLD",
          "NOR",
          "NPL",
          "NRU",
          "NZL",
          "OMN",
          "PAK",
          "PAN",
          "PCN",
          "PER",
          "PHL",
          "PLW",
          "PNG",
          "POL",
          "PRI",
          "PRK",
          "PRT",
          "PRY",
          "PSE",
          "PYF",
          "QAT",
          "REU",
          "ROU",
          "RUS",
          "RWA",
          "SAU",
          "SDN",
          "SEN",
          "SGP",
          "SGS",
          "SHN",
          "SJM",
          "SLB",
          "SLE",
          "SLV",
          "SMR",
          "SOM",
          "SPM",
          "SRB",
          "SSD",
          "STP",
          "SUR",
          "SVK",
          "SVN",
          "SWE",
          "SWZ",
          "SXM",
          "SYC",
          "SYR",
          "TCA",
          "TCD",
          "TGO",
          "THA",
          "TJK",
          "TKL",
          "TKM",
          "TLS",
          "TON",
          "TTO",
          "TUN",
          "TUR",
          "TUV",
          "TWN",
          "TZA",
          "UGA",
          "UKR",
          "UMI",
          "URY",
          "USA",
          "UZB",
          "VAT",
          "VCT",
          "VEN",
          "VGB",
          "VIR",
          "VNM",
          "VUT",
          "WLF",
          "WSM",
          "XKX",
          "YEM",
          "ZAF",
          "ZMB",
          "ZWE"
        ],
        "nullable": true
      },
      "address": {
        "type": "object",
        "properties": {
          "line1": {
            "type": "string",
            "minLength": 1,
            "description": "First line of the address (max 35 characters).",
            "nullable": true
          },
          "line2": {
            "type": "string",
            "minLength": 1,
            "description": "Second line of the address (max 35 characters).",
            "nullable": true
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "description": "City (max 20 characters).",
            "nullable": true
          },
          "region": {
            "type": "string",
            "minLength": 1,
            "description": "2-letter State code.",
            "nullable": true
          },
          "postal_code": {
            "type": "string",
            "minLength": 1,
            "description": "Zip or Postal code (max 7 characters).",
            "nullable": true
          },
          "country": {
            "$ref": "#/components/schemas/country"
          }
        },
        "required": [
          "city",
          "country",
          "line1",
          "postal_code",
          "region"
        ]
      },
      "additional_motor_vehicle_rental_data": {
        "type": "object",
        "nullable": true,
        "description": "Contains motor vehicle rental-specific fields for `Authorization` and `Transfer` requests. Optional for motor vehicle rental MCC transactions (MCC 3351–3500, 7512). Returns `null` for all other transactions.",
        "properties": {
          "motor_vehicle_rental_agreement_number": {
            "type": "string",
            "nullable": true,
            "description": "The rental agreement or contract reference number for the rental. Max 9 characters; longer values are truncated."
          },
          "customer_service_number": {
            "type": "string",
            "nullable": true,
            "description": "The phone number customers can call for support or inquiries related to their rental."
          },
          "extra_charge_details": {
            "type": "object",
            "nullable": true,
            "description": "Additional charges beyond the base rental rate being billed. Each field represents a specific charge type, in cents.",
            "properties": {
              "extra_mileage_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "fuel_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "insurance_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "late_return_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "one_way_service_fee_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "parking_violation_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              }
            }
          },
          "is_no_show": {
            "type": "boolean",
            "nullable": true,
            "default": false,
            "description": "An indicator that the cardholder is being billed for a reserved vehicle that was not actually rented (that is, a \"no-show\" charge)."
          },
          "number_of_days": {
            "type": "integer",
            "nullable": true,
            "description": "The total number of days for the vehicle rental."
          },
          "rental_rate": {
            "type": "string",
            "nullable": true,
            "description": "The daily rental rate for the vehicle, in cents."
          },
          "renter_name": {
            "type": "string",
            "nullable": true,
            "description": "The name of the person renting the vehicle."
          },
          "pickup_address": {
            "nullable": true,
            "description": "The full address of the rental pickup location.",
            "allOf": [
              {
                "$ref": "#/components/schemas/address"
              }
            ]
          },
          "pickup_date": {
            "type": "object",
            "nullable": true,
            "description": "The scheduled vehicle pickup date.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the pickup date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the pickup date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the pickup date."
              }
            }
          },
          "return_address": {
            "nullable": true,
            "description": "The full address of the vehicle return location.",
            "allOf": [
              {
                "$ref": "#/components/schemas/address"
              }
            ]
          },
          "return_date": {
            "type": "object",
            "nullable": true,
            "description": "The scheduled vehicle return date. Must be on or after `pickup_date`.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the return date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the return date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the return date."
              }
            }
          }
        }
      },
      "customer_reference_number": {
        "type": "string",
        "description": "A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records.",
        "maxLength": 17
      },
      "additional_purchase_data": {
        "type": "object",
        "description": "Additional information about the purchase used for [Level 2 and Level 3 Processing](/guides/online-payments/payment-features/level-2-level-3-processing). Please note that Visa is ending its Level 2 offering in April 2026.",
        "nullable": true,
        "properties": {
          "customer_reference_number": {
            "$ref": "#/components/schemas/customer_reference_number"
          },
          "customs_duty_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The duty in cents on the total purchase amount for the order."
          },
          "destination_country_code": {
            "type": "string",
            "nullable": true,
            "description": "The ISO country code of the order destination."
          },
          "destination_postal_code": {
            "type": "string",
            "nullable": true,
            "description": "The postal code of the order destination (10 characters).",
            "maxLength": 10
          },
          "discount_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The amount in cents of the discount for the order. You must include this field to qualify for Level 3 interchange benefits. Even if the value is (0), you should pass the field to qualify for Level 3."
          },
          "invoice_reference_number": {
            "type": "string",
            "nullable": true,
            "description": "The order's invoice number (max 15 characters).",
            "maxLength": 15
          },
          "order_date": {
            "type": "object",
            "nullable": true,
            "properties": {
              "day": {
                "type": "integer",
                "description": "Day of purchase (between 1 and 31)."
              },
              "month": {
                "type": "integer",
                "description": "Month of purchase (between 1 and 12)."
              },
              "year": {
                "type": "integer",
                "description": "Year of purchase (4-digit).",
                "minimum": 1990
              }
            }
          },
          "sales_tax": {
            "type": "integer",
            "nullable": true,
            "description": "- Total aggregate tax amount in cents for the entire purchase. Field is automatically calculated if you pass in the itemized tax amounts.\n- For non-taxable transactions either set `sales_tax` to 0 or omit from payload and also set `tax_exempt` to **True**.\n- Request must align so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`.\n- For Visa, this field no longer qualifies for lower interchange after April 17, 2026. Include `item_data` for Level 3 processing."
          },
          "sales_tax_finix_generated": {
            "type": "integer",
            "description": "The sales tax amount in cents Finix calculated from the `item_data` line items.",
            "nullable": true
          },
          "ship_from_postal_code": {
            "type": "string",
            "nullable": true,
            "description": "The postal code from where order is shipped (10 characters).",
            "maxLength": 10
          },
          "shipping_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The shipping cost in cents for the order.\n"
          },
          "tax_exempt": {
            "type": "boolean",
            "description": "- For tax exempt purchases set to **True**.\n- If set to **True**, request can't include `sales_tax`."
          },
          "item_data": {
            "type": "array",
            "description": "Additional information about the transaction. Used for Level 2 and Level 3 Processing.",
            "items": {
              "type": "object",
              "properties": {
                "amount_excluding_sales_tax": {
                  "type": "integer",
                  "description": "- Total cost of the line item in cents, excluding tax.\n- Must align with `sales_tax` so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`."
                },
                "amount_including_sales_tax": {
                  "type": "integer",
                  "description": "- Total cost of the line item in cents, including tax.\n- Must align with `sales_tax` so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`."
                },
                "commodity_code": {
                  "description": "A commodity code is a numeric code representing a particular product or service as defined by the National Institute of Governmental Purchasing. The code can be 3, 5, 7, or 11 digits in length. The longer the code the more granular the description of the product/service. (max 12 characters).",
                  "type": "string",
                  "maxLength": 12
                },
                "cost_per_unit": {
                  "type": "integer",
                  "description": "The price in cents, excluding tax, of one unit of the item purchased."
                },
                "item_description": {
                  "type": "string",
                  "description": "Required when `item_data` is supplied (max 25 characters).",
                  "maxLength": 25
                },
                "item_discount_amount": {
                  "type": "integer",
                  "description": "The item discount amount in cents. You must include this field to qualify for Level 3 interchange benefits. Even if the value is (0), you should pass the field to qualify for Level 3."
                },
                "merchant_product_code": {
                  "type": "string",
                  "description": "Merchant defined product code (max 12 characters).",
                  "maxLength": 12
                },
                "quantity": {
                  "type": "number",
                  "description": "The number of items purchased. Must be greater than 0.",
                  "minimum": 1,
                  "maximum": 99
                },
                "unit_of_measure": {
                  "type": "string",
                  "description": "The unit of measure of the purchased item (max 3 characters).",
                  "maxLength": 3
                },
                "sales_tax_amount": {
                  "type": "integer",
                  "description": "The sales tax amount in cents for the line item."
                },
                "sales_tax_rate": {
                  "type": "number",
                  "description": "The sales tax rate for the line item as a decimal (e.g., 0.25 equals 25%).",
                  "example": 0.25
                }
              }
            }
          }
        }
      },
      "amount": {
        "type": "integer",
        "description": "The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).",
        "example": 5000,
        "format": "int64"
      },
      "tags": {
        "type": "object",
        "title": "tags",
        "additionalProperties": true,
        "description": "Include up to 50 `key: value` pairs to annotate requests with custom metadata.\n- Maximum character length for individual `keys` is 40.\n- Maximum character length for individual `values` is 500.\n(For example, `order_number: 25`, `item_type: produce`, `department: sales`)",
        "nullable": true
      },
      "currency": {
        "type": "string",
        "description": "ISO 4217 3-letter currency code.",
        "enum": [
          "CAD",
          "USD"
        ]
      },
      "created_via_transfers_authorizations": {
        "type": "string",
        "description": "Gives more information about the product flow that was used to create the resource. Finix retains the right to add additional enums for this field without it being a breaking change.",
        "default": "UNKNOWN",
        "enum": [
          "CARD_PRESENT_ANDROID_APP",
          "CARD_PRESENT_ANDROID_APP_MANUAL_ENTRY",
          "CARD_PRESENT_ANDROID_D135_SDK",
          "CARD_PRESENT_DEVICE_READER_SDK",
          "CARD_PRESENT_IOS_APP",
          "CARD_PRESENT_IOS_APP_MANUAL_ENTRY",
          "CARD_PRESENT_IOS_D135_SDK",
          "CARD_PRESENT_IOS_TAP_TO_PAY",
          "CARD_PRESENT_IOS_TAP_TO_PAY_SDK",
          "CARD_PRESENT_SEMI_INTEGRATED_API",
          "CARD_PRESENT_STANDALONE",
          "CARD_PRESENT_STANDALONE_MANUAL_ENTRY",
          "CHECKOUT_FORM",
          "CYBERSOURCE",
          "DEVICE_ORDER",
          "PAYMENT_LINK",
          "PAYOUT_LINK",
          "PLUGIN_ADMOJI",
          "PLUGIN_CHECKOUT_CHAMP",
          "PLUGIN_FYNTEK",
          "PLUGIN_GAMBLE_ID",
          "PLUGIN_GAMMA_SWEEP",
          "PLUGIN_GR4VY",
          "PLUGIN_HYPERSWITCH",
          "PLUGIN_LACORE",
          "PLUGIN_PAYSIGHT",
          "PLUGIN_PRYZR",
          "PLUGIN_SERVMAN",
          "PLUGIN_SOAP_PAY",
          "PLUGIN_STICKYIO",
          "PLUGIN_TAGADA",
          "PLUGIN_WOO_COMMERCE",
          "PLUGIN_VRIO",
          "SUBSCRIPTION",
          "UNKNOWN",
          "VIRTUAL_TERMINAL"
        ]
      },
      "failure_code": {
        "type": "string",
        "description": "The code of the failure so the decline can be handled programmatically. For more info on how to handle the failure, see [Failure Codes](/additional-resources/developers/implementation-and-testing/failure-codes).",
        "nullable": true
      },
      "failure_message": {
        "type": "string",
        "description": "A human-readable description of why the transaction was declined. This will also include a suggestion on how to complete the payment.",
        "nullable": true
      },
      "fee_transfer": {
        "type": "integer",
        "format": "int64",
        "description": "The minimum amount of the `Transfer` you'd like to collect as your fee in cents. Defaults to zero (must be less than or equal to the `amount`).\n- If the fees applied by the 'Fee Profile' are ***higher*** than the value passed in 'fee', 'fee' will not be applied and have no effect.\n- If the fees applied by the 'Fee Profile' are ***lower*** than the value passed in 'fee', an additional fee is be applied, in addition to the fees generated by the `Fee Profile`.\n    - The additional fee is equal to the difference between the value passed in 'fee' and the fees generated by the `Fee Profile`."
      },
      "funds_flow_type": {
        "type": "string",
        "description": "The type of disbursement to perform. Defaults to `GENERAL_PAYOUT`.\n",
        "enum": [
          "GENERAL_PAYOUT",
          "ME_TO_ME",
          "GOVERNMENT"
        ],
        "nullable": true
      },
      "idempotency_id": {
        "type": "string",
        "description": "Pass any randomly generated or internal ID to [idempotently](/api/section/idempotent-requests) identify `Transfers`, `Authorizations`, or refund requests.",
        "nullable": true
      },
      "statement_descriptor": {
        "type": "string",
        "maxLength": 20,
        "nullable": true,
        "description": "The description of the `Merchant` that appears on the buyer's bank or card statement."
      },
      "application_link": {
        "type": "object",
        "description": "Link to the `Application` the request was made under.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "self": {
        "type": "object",
        "description": "Link to the resource that was used in the request.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "transfer": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/id"
          },
          "created_at": {
            "$ref": "#/components/schemas/created_at"
          },
          "updated_at": {
            "$ref": "#/components/schemas/updated_at"
          },
          "3d_secure_session": {
            "type": "string",
            "nullable": true,
            "description": "The ID of the `3D Secure Session` that authenticated the buyer. This field is `null` when the payment was not authenticated with a `3D Secure Session`.",
            "example": "3d_secure_session_f3fG3Zj8K958MTP5vpXAXX"
          },
          "additional_buyer_charges": {
            "description": "Details about any [Buyer Charges](../../../../guides/online-payments/payment-features/buyer-charges) included in the `Transfer`. The buyer charges are mutually exclusive.\n",
            "allOf": [
              {
                "$ref": "#/components/schemas/additional_buyer_charges"
              }
            ]
          },
          "additional_healthcare_data": {
            "$ref": "#/components/schemas/additional_healthcare_data"
          },
          "additional_lodging_data": {
            "$ref": "#/components/schemas/additional_lodging_data"
          },
          "additional_motor_vehicle_rental_data": {
            "$ref": "#/components/schemas/additional_motor_vehicle_rental_data"
          },
          "additional_purchase_data": {
            "$ref": "#/components/schemas/additional_purchase_data"
          },
          "address_verification": {
            "type": "string",
            "description": "Details the results of the address verification checks.",
            "nullable": true,
            "enum": [
              "POSTAL_CODE_AND_STREET_MATCH",
              "STREET_MATCH",
              "POSTAL_CODE_MATCH",
              "NO_ADDRESS",
              "NO_MATCH",
              "NOT_SUPPORTED",
              "UNKNOWN"
            ]
          },
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "amount_requested": {
            "type": "integer",
            "format": "int64",
            "description": "The `amount` that was requested to get debited from the `source` when the transaction was created, in cents (e.g., `100` = $1.00).",
            "example": 100
          },
          "application": {
            "type": "string",
            "minLength": 1,
            "description": "ID of the `Application` associated with the resource."
          },
          "bank_return_details": {
            "type": "object",
            "description": "Details about a transfer that was returned and was unable to be processed. Only present when `state` is `RETURNED`",
            "nullable": true,
            "properties": {
              "reason_code": {
                "type": "string",
                "description": "Return response code from the bank."
              },
              "reason_message": {
                "type": "string",
                "description": "Detailed message explaining reason for the return."
              },
              "reason_title": {
                "type": "string",
                "description": "Short message categorizing reason for the return."
              }
            }
          },
          "card_present_details": {
            "type": "object",
            "description": "Details needed to process card present transactions.",
            "nullable": true,
            "properties": {
              "approval_code": {
                "type": "string",
                "description": "Unique ID used to identify the approval of the `Transfer`.",
                "nullable": true
              },
              "brand": {
                "type": "string",
                "description": "The brand of the card saved in the `Payment Instrument`.",
                "nullable": true
              },
              "emv_data": {
                "type": "object",
                "description": "Encrypted card data used to process the transaction.",
                "nullable": true,
                "properties": {
                  "application_identifier": {
                    "type": "string",
                    "description": "ID of the application used in the transaction. Tag 9F06 from the EMVCo standard.",
                    "nullable": true
                  },
                  "application_label": {
                    "type": "string",
                    "description": "EMV application label. Tag 50 from the EMVCo standard.",
                    "nullable": true
                  },
                  "application_preferred_name": {
                    "type": "string",
                    "description": "EMV application label with formatting (if provided). Tag 9F12 from the EMVCo standard.",
                    "nullable": true
                  },
                  "application_transaction_counter": {
                    "type": "string",
                    "description": "Transaction number for the EMV application. Tag 9F36 from the EMVCo standard.",
                    "nullable": true
                  },
                  "cryptogram": {
                    "type": "string",
                    "description": "Cryptogram returned by the card. Tag 9F26 of the EMVCo standard.",
                    "nullable": true
                  },
                  "issuer_code_table_index": {
                    "type": "string",
                    "description": "The alphabet code table (according to ISO 8859) used by the EMV application (if provided). Tag 9F11.",
                    "nullable": true
                  },
                  "network_emv_response": {
                    "type": "string",
                    "description": "EMV response data returned by the card network.",
                    "nullable": true
                  },
                  "pin_verified": {
                    "type": "boolean",
                    "description": "Whether the cardholder's PIN number was verified."
                  },
                  "tags": {
                    "$ref": "#/components/schemas/tags"
                  }
                }
              },
              "entry_mode": {
                "type": "string",
                "description": "Details of the card payment method used to process the transaction.\n\nThe possible enums are:\n\n- UNKNOWN - The method by which the payment card was used is unknown.\n- SWIPED - The card was swiped through a POS terminal.\n- CONTACTLESS - The payment was made by tapping a card on a POS terminal.\n- CHIP_ENTRY - The payment card was inserted into a card reader.\n",
                "enum": [
                  "UNKNOWN",
                  "SWIPED",
                  "CONTACTLESS",
                  "CHIP_ENTRY"
                ],
                "nullable": true
              },
              "masked_account_number": {
                "type": "string",
                "description": "Last four digits of the bank account number.",
                "nullable": true
              },
              "name": {
                "type": "string",
                "description": "The name of the bank account or card owner.",
                "nullable": true
              },
              "digital_signature_file_id": {
                "type": "string",
                "description": "The ID of the file containing the digital signature captured during the transaction. If a signature was not collected, this field returns `null`.",
                "nullable": true
              },
              "payment_type": {
                "type": "string",
                "description": "The type of `Payment Instrument` used in the transaction (or the original payment).",
                "nullable": true
              }
            }
          },
          "currency": {
            "$ref": "#/components/schemas/currency"
          },
          "created_via": {
            "$ref": "#/components/schemas/created_via_transfers_authorizations"
          },
          "destination": {
            "type": "string",
            "description": "ID of the `Payment Instrument` where funds will be sent.",
            "nullable": true
          },
          "device": {
            "type": "string",
            "description": "The ID of the `Device` resource the `Transfer` was created under."
          },
          "externally_funded": {
            "type": "string",
            "description": "Details if the `Transfer` will be settled externally by card processors."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp indicating when a held refund expires. Only returned for reversals created with refund holds enabled. A refund that can't be covered by this time fails with `failure_code: REFUND_EXPIRED`. For more information, see [Pending refunds](/guides/after-the-payment/refunds/pending-refunds).",
            "nullable": true
          },
          "failure_code": {
            "$ref": "#/components/schemas/failure_code"
          },
          "failure_message": {
            "$ref": "#/components/schemas/failure_message"
          },
          "fee": {
            "$ref": "#/components/schemas/fee_transfer"
          },
          "fee_profile": {
            "type": "string",
            "description": "The ID of the `Fee Profile` that will be used for calculating fees for this transfer."
          },
          "funds_flow_type": {
            "$ref": "#/components/schemas/funds_flow_type"
          },
          "idempotency_id": {
            "$ref": "#/components/schemas/idempotency_id"
          },
          "ip_address_details": {
            "type": "object",
            "description": "Always returns `null`.",
            "nullable": true
          },
          "merchant": {
            "type": "string",
            "description": "The ID of the `Merchant` resource the `Transfer` was created under.",
            "example": "MUxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "merchant_identity": {
            "type": "string",
            "example": "IDxxxxxxxxxxxxxxxxxxxxxxxx",
            "description": "The ID of `Identity` resource used by the `Merchant` the `Transfer` was created under."
          },
          "messages": {
            "type": "array",
            "description": "A list of messages that provides additional details.",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "network_details": {
            "type": "object",
            "nullable": true,
            "description": "Contains network-specific fields used by issuers to identify transactions.",
            "properties": {
              "brand": {
                "type": "string",
                "description": "Card brand associated with the saved payment instrument.",
                "example": "VISA"
              },
              "authorization_code": {
                "type": "string",
                "description": "Code returned by the issuing bank when a transaction is authorized.",
                "example": 840735
              },
              "acquirer_reference_number": {
                "type": "string",
                "description": "Unique identifier banks use to trace chargebacks or refunds. Available only for Mastercard transactions; otherwise returns `null`.",
                "nullable": true,
                "example": 521600805857
              }
            }
          },
          "operation_key": {
            "type": "string",
            "enum": [
              "CARD_NOT_PRESENT_CAPTURE",
              "CARD_NOT_PRESENT_REFUND",
              "CARD_NOT_PRESENT_SALE",
              "CARD_NOT_PRESENT_UNREFERENCED_REFUND",
              "CARD_PRESENT_AUTHORIZATION",
              "CARD_PRESENT_DEBIT",
              "CARD_PRESENT_SALE",
              "CARD_PRESENT_UNREFERENCED_REFUND",
              "INSTANT_APPLICATION_FUNDING_PULL_FROM_ACH",
              "INSTANT_APPLICATION_FUNDING_PULL_FROM_CARD",
              "INSTANT_APPLICATION_FUNDING_PULL_FROM_FED_NOW",
              "INSTANT_APPLICATION_FUNDING_PULL_FROM_SAME_DAY_ACH",
              "INSTANT_APPLICATION_FUNDING_PUSH_TO_ACH",
              "INSTANT_APPLICATION_FUNDING_PUSH_TO_CARD",
              "INSTANT_APPLICATION_FUNDING_PUSH_TO_FED_NOW",
              "INSTANT_APPLICATION_FUNDING_PUSH_TO_SAME_DAY_ACH",
              "INSTANT_MERCHANT_FUNDING_PULL_FROM_ACH",
              "INSTANT_MERCHANT_FUNDING_PULL_FROM_FED_NOW",
              "INSTANT_MERCHANT_FUNDING_PULL_FROM_SAME_DAY_ACH",
              "INSTANT_MERCHANT_FUNDING_PUSH_TO_ACH",
              "INSTANT_MERCHANT_FUNDING_PUSH_TO_CARD",
              "INSTANT_MERCHANT_FUNDING_PUSH_TO_FED_NOW",
              "INSTANT_MERCHANT_FUNDING_PUSH_TO_SAME_DAY_ACH",
              "MERCHANT_CREDIT_ADJUSTMENT",
              "MERCHANT_DEBIT_ADJUSTMENT",
              "PULL_FROM_ACH",
              "PULL_FROM_CARD",
              "PULL_FROM_SAME_DAY_ACH",
              "PUSH_TO_ACH",
              "PUSH_TO_CARD",
              "PUSH_TO_SAME_DAY_ACH",
              "REFUND_MERCHANT_CREDIT_ADJUSTMENT",
              "REFUND_MERCHANT_DEBIT_ADJUSTMENT",
              "SALE",
              "STANDARD_APPLICATION_FUNDING_PULL_FROM_ACH",
              "STANDARD_APPLICATION_FUNDING_PULL_FROM_CARD",
              "STANDARD_APPLICATION_FUNDING_PULL_FROM_SAME_DAY_ACH",
              "STANDARD_APPLICATION_FUNDING_PUSH_TO_ACH",
              "STANDARD_APPLICATION_FUNDING_PUSH_TO_CARD",
              "STANDARD_APPLICATION_FUNDING_PUSH_TO_SAME_DAY_ACH",
              "STANDARD_MERCHANT_FUNDING_PULL_FROM_ACH",
              "STANDARD_MERCHANT_FUNDING_PULL_FROM_CARD",
              "STANDARD_MERCHANT_FUNDING_PULL_FROM_SAME_DAY_ACH",
              "STANDARD_MERCHANT_FUNDING_PUSH_TO_ACH",
              "STANDARD_MERCHANT_FUNDING_PUSH_TO_CARD",
              "STANDARD_MERCHANT_FUNDING_PUSH_TO_SAME_DAY_ACH",
              "UNREFERENCED_REFUND"
            ],
            "description": "The operation performed in the transaction. `REFUND_MERCHANT_DEBIT_ADJUSTMENT` and `REFUND_MERCHANT_CREDIT_ADJUSTMENT` are created by Finix for [refund holds](/guides/after-the-payment/refunds/pending-refunds) and cannot be passed in requests.",
            "nullable": true
          },
          "parent_transfer": {
            "type": "string",
            "description": "ID of the original parent `Transfer`. Only present when `type` is `REVERSAL`.",
            "nullable": true
          },
          "parent_transfer_trace_id": {
            "type": "string",
            "description": "The `trace_id` of the original parent `Transfer`. Only present when `type` is `REVERSAL`.",
            "nullable": true
          },
          "processed_at": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp of when the `Transfer` was processed.",
            "nullable": true
          },
          "pull_transfer_id": {
            "type": "string",
            "nullable": true,
            "description": "The ID of the corresponding pull `Transfer` linked in a `ME_TO_ME` transaction."
          },
          "raw": {
            "description": "Raw response from the processor.",
            "anyOf": [
              {
                "type": "object",
                "nullable": true
              },
              {
                "type": "string",
                "nullable": true
              }
            ]
          },
          "ready_to_settle_at": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp indicating when the `Transfer` is ready to be settled.",
            "nullable": true
          },
          "receipt_last_printed_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the receipt was last printed.",
            "nullable": true
          },
          "security_code_verification": {
            "type": "string",
            "nullable": true,
            "description": "Details the results of the Card Verification Code check.",
            "enum": [
              "MATCHED",
              "UNKNOWN",
              "UNMATCHED"
            ]
          },
          "source": {
            "type": "string",
            "description": "The ID of the `Payment Instrument` that will be debited and performing the `Transfer`.",
            "nullable": true
          },
          "split_transfers": {
            "type": "array",
            "description": "Array containing the resource IDs of the `Split Transfers` generated from the `Transfer`.\n\nFor standard split transactions, this contains IDs of `Split Transfers` created from the parent `Transfer`.\n\nFor [dispute adjustment transfers](/api/disputes/listdisputesadjustments) on split transactions:\n- When a `MERCHANT_DEBIT` or `MERCHANT_CREDIT` adjustment `Transfer` is created for a [Dispute](/api/disputes) on a split transaction, this array contains the IDs of `Split Transfers` created for each participant.\n- The `Split Transfers` are created proportionally based on each merchant's share of the original sale.\n\nFor more information, see [Split Transactions - Disputes](../../../../guides/online-payments/payment-features/split-transactions#disputes).\n",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "state": {
            "type": "string",
            "enum": [
              "CANCELED",
              "PENDING",
              "FAILED",
              "SUCCEEDED",
              "UNKNOWN",
              "RETURNED"
            ],
            "description": "The status of the `Transfer`."
          },
          "statement_descriptor": {
            "$ref": "#/components/schemas/statement_descriptor"
          },
          "subtype": {
            "type": "string",
            "description": "Additional information describing the `payment_type`.\n\nFor [dispute adjustment transfers](/api/disputes/listdisputesadjustments) (`type: DISPUTE`):\n- `MERCHANT_DEBIT`: Funds are pulled from the merchant(s) when a chargeback occurs. For split transactions, this creates `Split Transfers` with `type: DISPUTE_MERCHANT_DEBIT`.\n- `MERCHANT_CREDIT`: Funds are returned to the merchant(s) when a `Dispute` is ruled in their favor. For split transactions, this creates `Split Transfers` with `type: DISPUTE_MERCHANT_CREDIT`.\n\nFor [refund hold](/guides/after-the-payment/refunds/pending-refunds) adjustment transfers:\n- `REFUND_MERCHANT_DEBIT_ADJUSTMENT`: Funds are pulled from the merchant to cover a held refund.\n- `REFUND_MERCHANT_CREDIT_ADJUSTMENT`: Funds are returned to the merchant when the held refund is submitted or expires.\n",
            "enum": [
              "API",
              "DISPUTE",
              "MERCHANT_CREDIT",
              "MERCHANT_CREDIT_ADJUSTMENT",
              "MERCHANT_DEBIT",
              "MERCHANT_DEBIT_ADJUSTMENT",
              "PLATFORM_CREDIT",
              "PLATFORM_CREDIT_ADJUSTMENT",
              "PLATFORM_DEBIT",
              "PLATFORM_DEBIT_ADJUSTMENT",
              "REFUND_MERCHANT_CREDIT_ADJUSTMENT",
              "REFUND_MERCHANT_DEBIT_ADJUSTMENT",
              "SETTLEMENT_MERCHANT",
              "SETTLEMENT_NOOP",
              "SETTLEMENT_PARTNER",
              "SETTLEMENT_PLATFORM",
              "SPLIT_PAYOUT",
              "SPLIT_PAYOUT_ADJUSTMENT",
              "SYSTEM"
            ]
          },
          "supplemental_fee": {
            "type": "string",
            "description": "Amount in cents for which an additional fee will be created in addition to any fees created from the assigned fee profile.",
            "nullable": true
          },
          "tags": {
            "$ref": "#/components/schemas/tags"
          },
          "tip_amount": {
            "type": "integer",
            "description": "The tip amount included in the total amount.",
            "nullable": true
          },
          "trace_id": {
            "type": "string",
            "description": "Trace ID of the `Transfer`. The processor sends back the `trace_id` so you can track the `Transfer` end-to-end.",
            "nullable": true
          },
          "type": {
            "type": "string",
            "description": "Type of `Transfer`.",
            "enum": [
              "DEBIT",
              "CREDIT",
              "REVERSAL",
              "ADJUSTMENT",
              "DISPUTE",
              "RESERVE",
              "SETTLEMENT",
              "UNKNOWN"
            ]
          },
          "third_party_details": {
            "type": "object",
            "description": "Details about the third-party processor associated with the `Transfer`.",
            "nullable": true,
            "properties": {
              "external_trace_id": {
                "type": "string",
                "description": "The trace ID returned by the third-party processor used to identify the `Transfer`.",
                "nullable": true
              },
              "type": {
                "type": "string",
                "description": "The name of the third-party processor associated with the `Transfer`.",
                "nullable": true,
                "enum": [
                  "CYBERSOURCE"
                ]
              }
            }
          },
          "_links": {
            "type": "object",
            "properties": {
              "application": {
                "$ref": "#/components/schemas/application_link"
              },
              "destination": {
                "type": "object",
                "description": "Link to the `Payment Instrument` where funds are getting sent.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "device": {
                "type": "object",
                "description": "Link to the `Device` the request was made under.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "disputes": {
                "type": "object",
                "description": "Link to the `Dispute` the request was made under.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "fee_profile": {
                "type": "object",
                "description": "Link to the `fee_profile` the request was made under.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "fees": {
                "type": "object",
                "description": "Link to the `fees` the request is associated with.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "merchant_identity": {
                "type": "object",
                "description": "Link to the `Identity` the `Merchant` was created under and the `Transfer` was submitted with.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "payment_instruments": {
                "type": "object",
                "description": "Link to the `Payment Instrument` associated with the Transfer.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "disputed_transfer": {
                "type": "object",
                "description": "Link to the `Transfer` the `Dispute` is about.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "parent": {
                "type": "object",
                "description": "Link to the original resource that was used in the request.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "reversals": {
                "type": "object",
                "description": "Link to the `reversals` associated with the `Transfer`.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "self": {
                "$ref": "#/components/schemas/self"
              },
              "source": {
                "type": "object",
                "description": "Link to the `Payment Instrument` the `Transfer` was created under.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## Create a Sale with Level 3 processing

Send a POST /transfers request and include the required fields for Level 3 processing.

### Level 3 Fields

Include the following `additional_purchase_data` fields:

| Field | API Field | Type | Description |
|  --- | --- | --- | --- |
| **Customer Reference Number** | `customer_reference_number` | *string*, **required** | A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records. (max `17` characters) |
| **Customs Duty Amount** | `customs_duty_amount` | *integer*, **required** | The costs related to import or export duties in cents. This field must have a value of at least `0`. |
| **Discount Amount** | `discount_amount` | *integer*, **required** | The amount in cents of the discount for the order. This field must have a value of at least `0`. |
| **Shipping Amount** | `shipping_amount` | *integer*, **required** | The costs related to shipping and handling in cents. This field must have a value of at least `0`. |
| **Tax Exempt** | `tax_exempt` | *boolean*, **optional** | For tax exempt purchases set to `true`. |


Include the following `item_data` fields for each line item:

| Field | API Field | Type | Description |
|  --- | --- | --- | --- |
| **Amount Excluding Sales Tax** | `amount_excluding_sales_tax` | *integer*, **required** | Total cost in cents of the line item excluding tax (must be greater than `0`). |
| **Amount Including Sales Tax** | `amount_including_sales_tax` | *integer*, **required** | Total cost in cents of the line item including tax (must be greater than `0`). |
| **Commodity Code** | `commodity_code` | *string*, **required** | A commodity code is a numeric code representing a particular product or service as defined by the National Institute of Governmental Purchasing. The code can be `3`, `5`, `7`, or `11` digits in length. The longer the code the more granular the description of the product/service. (max 12 characters) |
| **Cost per Item** | `cost_per_unit` | *integer*, **required** | The price in cents of one unit of the item purchased. |
| **Item Description** | `item_description` | *string*, **required** | A short, human-readable description of the line item (max `25` characters). |
| **Item Discount** | `item_discount_amount` | *integer*, **required** | The discount amount in cents applied to this individual line item. For an order-level discount, use `discount_amount`. |
| **Merchant Product Code** | `merchant_product_code` | *string*, **required** | Merchant defined product code (max `12` characters). |
| **Quantity** | `quantity` | *integer*, **required** | The number of items purchased. Must be greater than `0`. |
| **Unit of Measure** | `unit_of_measure` | *string*, **required** | The unit of measure of the purchased item (max `3` characters). |


Example
### Request

```shell
curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/transfers \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "additional_purchase_data": {
      "customer_reference_number": "PO-2024-3842",
      "customs_duty_amount": 0,
      "discount_amount": 100,
      "item_data": [
        {
          "amount_excluding_sales_tax": 400,
          "amount_including_sales_tax": 440,
          "commodity_code": "175-62-20",
          "cost_per_unit": 500,
          "item_description": "IT Network Assessment",
          "item_discount_amount": 100,
          "merchant_product_code": "SVC-NET-ASMT",
          "quantity": 1,
          "unit_of_measure": "HUR"
        },
        {
          "amount_excluding_sales_tax": 500,
          "amount_including_sales_tax": 550,
          "commodity_code": "207-72-54",
          "cost_per_unit": 500,
          "item_description": "USB-C Charging Cable 6ft",
          "item_discount_amount": 0,
          "merchant_product_code": "CBL-USBC-6FT",
          "quantity": 1,
          "unit_of_measure": "EA"
        }
      ],
      "shipping_amount": 100
    },
    "amount": 990,
    "currency": "USD",
    "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
    "source": "PIkxmtueemLD6dN9ZoWGHT44"
  }'
```

API Definition
```json
{
  "$ref": "#/components/schemas/createTransferLvl3Processing",
  "components": {
    "schemas": {
      "customer_reference_number": {
        "type": "string",
        "description": "A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records.",
        "maxLength": 17
      },
      "additional_purchase_data": {
        "type": "object",
        "description": "Additional information about the purchase used for [Level 2 and Level 3 Processing](/guides/online-payments/payment-features/level-2-level-3-processing). Please note that Visa is ending its Level 2 offering in April 2026.",
        "nullable": true,
        "properties": {
          "customer_reference_number": {
            "$ref": "#/components/schemas/customer_reference_number"
          },
          "customs_duty_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The duty in cents on the total purchase amount for the order."
          },
          "destination_country_code": {
            "type": "string",
            "nullable": true,
            "description": "The ISO country code of the order destination."
          },
          "destination_postal_code": {
            "type": "string",
            "nullable": true,
            "description": "The postal code of the order destination (10 characters).",
            "maxLength": 10
          },
          "discount_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The amount in cents of the discount for the order. You must include this field to qualify for Level 3 interchange benefits. Even if the value is (0), you should pass the field to qualify for Level 3."
          },
          "invoice_reference_number": {
            "type": "string",
            "nullable": true,
            "description": "The order's invoice number (max 15 characters).",
            "maxLength": 15
          },
          "order_date": {
            "type": "object",
            "nullable": true,
            "properties": {
              "day": {
                "type": "integer",
                "description": "Day of purchase (between 1 and 31)."
              },
              "month": {
                "type": "integer",
                "description": "Month of purchase (between 1 and 12)."
              },
              "year": {
                "type": "integer",
                "description": "Year of purchase (4-digit).",
                "minimum": 1990
              }
            }
          },
          "sales_tax": {
            "type": "integer",
            "nullable": true,
            "description": "- Total aggregate tax amount in cents for the entire purchase. Field is automatically calculated if you pass in the itemized tax amounts.\n- For non-taxable transactions either set `sales_tax` to 0 or omit from payload and also set `tax_exempt` to **True**.\n- Request must align so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`.\n- For Visa, this field no longer qualifies for lower interchange after April 17, 2026. Include `item_data` for Level 3 processing."
          },
          "sales_tax_finix_generated": {
            "type": "integer",
            "description": "The sales tax amount in cents Finix calculated from the `item_data` line items.",
            "nullable": true
          },
          "ship_from_postal_code": {
            "type": "string",
            "nullable": true,
            "description": "The postal code from where order is shipped (10 characters).",
            "maxLength": 10
          },
          "shipping_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The shipping cost in cents for the order.\n"
          },
          "tax_exempt": {
            "type": "boolean",
            "description": "- For tax exempt purchases set to **True**.\n- If set to **True**, request can't include `sales_tax`."
          },
          "item_data": {
            "type": "array",
            "description": "Additional information about the transaction. Used for Level 2 and Level 3 Processing.",
            "items": {
              "type": "object",
              "properties": {
                "amount_excluding_sales_tax": {
                  "type": "integer",
                  "description": "- Total cost of the line item in cents, excluding tax.\n- Must align with `sales_tax` so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`."
                },
                "amount_including_sales_tax": {
                  "type": "integer",
                  "description": "- Total cost of the line item in cents, including tax.\n- Must align with `sales_tax` so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`."
                },
                "commodity_code": {
                  "description": "A commodity code is a numeric code representing a particular product or service as defined by the National Institute of Governmental Purchasing. The code can be 3, 5, 7, or 11 digits in length. The longer the code the more granular the description of the product/service. (max 12 characters).",
                  "type": "string",
                  "maxLength": 12
                },
                "cost_per_unit": {
                  "type": "integer",
                  "description": "The price in cents, excluding tax, of one unit of the item purchased."
                },
                "item_description": {
                  "type": "string",
                  "description": "Required when `item_data` is supplied (max 25 characters).",
                  "maxLength": 25
                },
                "item_discount_amount": {
                  "type": "integer",
                  "description": "The item discount amount in cents. You must include this field to qualify for Level 3 interchange benefits. Even if the value is (0), you should pass the field to qualify for Level 3."
                },
                "merchant_product_code": {
                  "type": "string",
                  "description": "Merchant defined product code (max 12 characters).",
                  "maxLength": 12
                },
                "quantity": {
                  "type": "number",
                  "description": "The number of items purchased. Must be greater than 0.",
                  "minimum": 1,
                  "maximum": 99
                },
                "unit_of_measure": {
                  "type": "string",
                  "description": "The unit of measure of the purchased item (max 3 characters).",
                  "maxLength": 3
                },
                "sales_tax_amount": {
                  "type": "integer",
                  "description": "The sales tax amount in cents for the line item."
                },
                "sales_tax_rate": {
                  "type": "number",
                  "description": "The sales tax rate for the line item as a decimal (e.g., 0.25 equals 25%).",
                  "example": 0.25
                }
              }
            }
          }
        }
      },
      "amount": {
        "type": "integer",
        "description": "The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).",
        "example": 5000,
        "format": "int64"
      },
      "currency": {
        "type": "string",
        "description": "ISO 4217 3-letter currency code.",
        "enum": [
          "CAD",
          "USD"
        ]
      },
      "source": {
        "type": "string",
        "example": "PIxxxxxxxxxxxxxxxxxx",
        "description": "ID of the `Payment Instrument` where funds get debited."
      },
      "statement_descriptor": {
        "type": "string",
        "maxLength": 20,
        "nullable": true,
        "description": "The description of the `Merchant` that appears on the buyer's bank or card statement."
      },
      "tags": {
        "type": "object",
        "title": "tags",
        "additionalProperties": true,
        "description": "Include up to 50 `key: value` pairs to annotate requests with custom metadata.\n- Maximum character length for individual `keys` is 40.\n- Maximum character length for individual `values` is 500.\n(For example, `order_number: 25`, `item_type: produce`, `department: sales`)",
        "nullable": true
      },
      "createTransferLvl3Processing": {
        "title": "Transfer - Level 3 Processing",
        "properties": {
          "additional_purchase_data": {
            "$ref": "#/components/schemas/additional_purchase_data"
          },
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "currency": {
            "$ref": "#/components/schemas/currency"
          },
          "merchant": {
            "type": "string",
            "description": "The ID of the `Merchant` under which to create the `Transfer`."
          },
          "source": {
            "$ref": "#/components/schemas/source"
          },
          "statement_descriptor": {
            "$ref": "#/components/schemas/statement_descriptor"
          },
          "tags": {
            "$ref": "#/components/schemas/tags"
          }
        },
        "required": [
          "amount",
          "currency",
          "merchant",
          "source"
        ]
      }
    }
  }
}
```

### Response

A successful request returns a `201 Created` status code and includes a Transfer resource with Level 3 processing details:

Example
Transfer - Level 3 Processing
```json Transfer - Level 3 Processing
{
  "id": "TRfwbgfgsSV664hPUPfpvScc",
  "created_at": "2026-10-27T20:24:49.75Z",
  "updated_at": "2026-10-27T20:24:49.75Z",
  "3d_secure_session": null,
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_lodging_data": null,
  "additional_motor_vehicle_rental_data": null,
  "additional_purchase_data": { // [!code highlight]
    "customer_reference_number": "PO-2024-3842", // [!code highlight]
    "customs_duty_amount": 0, // [!code highlight]
    "destination_country_code": null, // [!code highlight]
    "destination_postal_code": null, // [!code highlight]
    "discount_amount": 100, // [!code highlight]
    "invoice_reference_number": null, // [!code highlight]
    "order_date": null, // [!code highlight]
    "sales_tax": null, // [!code highlight]
    "sales_tax_finix_generated": 90, // [!code highlight]
    "ship_from_postal_code": null, // [!code highlight]
    "shipping_amount": 100, // [!code highlight]
    "tax_exempt": false, // [!code highlight]
    "item_data": [ // [!code highlight]
      { // [!code highlight]
        "cost_per_unit": 500, // [!code highlight]
        "item_description": "IT Network Assessment", // [!code highlight]
        "item_discount_amount": 100, // [!code highlight]
        "merchant_product_code": "SVC-NET-ASMT", // [!code highlight]
        "quantity": 1, // [!code highlight]
        "amount_excluding_sales_tax": 400, // [!code highlight]
        "amount_including_sales_tax": 440, // [!code highlight]
        "unit_of_measure": "HUR", // [!code highlight]
        "commodity_code": "175-62-20", // [!code highlight]
        "sales_tax_amount": 40, // [!code highlight]
        "sales_tax_rate": 0.1 // [!code highlight]
      }, // [!code highlight]
      { // [!code highlight]
        "cost_per_unit": 500, // [!code highlight]
        "item_description": "USB-C Charging Cable 6ft", // [!code highlight]
        "item_discount_amount": 0, // [!code highlight]
        "merchant_product_code": "CBL-USBC-6FT", // [!code highlight]
        "quantity": 1, // [!code highlight]
        "amount_excluding_sales_tax": 500, // [!code highlight]
        "amount_including_sales_tax": 550, // [!code highlight]
        "unit_of_measure": "EA", // [!code highlight]
        "commodity_code": "207-72-54", // [!code highlight]
        "sales_tax_amount": 50, // [!code highlight]
        "sales_tax_rate": 0.1 // [!code highlight]
      } // [!code highlight]
    ] // [!code highlight]
  }, // [!code highlight]
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "amount": 990,
  "amount_requested": 990,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_via": "UNKNOWN",
  "currency": "USD",
  "destination": null,
  "externally_funded": "UNKNOWN",
  "failure_code": null,
  "failure_message": null,
  "fee": 0,
  "fee_profile": "FPryaDMUDq9Tcc5epVpro1Jj",
  "idempotency_id": null,
  "ip_address_details": null,
  "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
  "merchant_identity": "IDjvxGeXBLKH1V9YnWm1CS4n",
  "messages": [],
  "network_details": {
    "brand": "VISA",
    "authorization_code": "099376",
    "acquirer_reference_number": null
  },
  "operation_key": "CARD_NOT_PRESENT_SALE",
  "parent_transfer": null,
  "parent_transfer_trace_id": null,
  "processed_at": "2026-10-27T20:24:50.21Z",
  "raw": null,
  "ready_to_settle_at": "2026-10-28T20:24:49.75Z",
  "receipt_last_printed_at": null,
  "security_code_verification": "MATCHED",
  "source": "PIkxmtueemLD6dN9ZoWGHT44",
  "split_transfers": [],
  "state": "SUCCEEDED",
  "statement_descriptor": "FLX*FLEX",
  "subtype": "API",
  "supplemental_fee": null,
  "tags": {},
  "third_party_details": null,
  "tip_amount": null,
  "trace_id": "73f9986c-58fe-4459-99b7-fa0775eefbc1",
  "type": "DEBIT",
  "_links": {
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "self": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRfwbgfgsSV664hPUPfpvScc"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRfwbgfgsSV664hPUPfpvScc/payment_instruments"
    },
    "reversals": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRfwbgfgsSV664hPUPfpvScc/reversals"
    },
    "fees": {
      "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRfwbgfgsSV664hPUPfpvScc"
    },
    "disputes": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRfwbgfgsSV664hPUPfpvScc/disputes"
    },
    "source": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkxmtueemLD6dN9ZoWGHT44"
    },
    "fee_profile": {
      "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPryaDMUDq9Tcc5epVpro1Jj"
    }
  }
}
```

API Definition
```json
{
  "$ref": "#/components/schemas/transfer",
  "components": {
    "schemas": {
      "id": {
        "type": "string",
        "minLength": 1,
        "description": "The ID of the resource."
      },
      "created_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was created."
      },
      "updated_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was last updated."
      },
      "additional_buyer_charges": {
        "type": "object",
        "description": "Additional charges will be incurred by the buyer.\n\nThe following rules apply:\n\n- The `Merchant` must be enabled to charge these surcharges by setting the appropriate flags for each applicable surcharge to `true` using the PUT `/merchants` endpoint.\n- Only _one_ of the following charges can be applied during creation.\n",
        "nullable": true,
        "properties": {
          "convenience_amount": {
            "type": "integer",
            "description": "A convenience fee to charge the buyer for the transaction. This object property is mutually exclusive.",
            "nullable": true
          },
          "rent_surcharge_amount": {
            "type": "integer",
            "description": "A rent surcharge to charge the buyer for the transaction. This object property is mutually exclusive.",
            "nullable": true
          },
          "surcharge_amount": {
            "type": "integer",
            "description": "A surcharge amount to charge the buyer for the transaction. This object property is mutually exclusive.",
            "nullable": true
          }
        }
      },
      "additional_healthcare_data": {
        "type": "object",
        "nullable": true,
        "properties": {
          "clinic_amount": {
            "type": "integer",
            "description": "A clinic or other qualified medical amount for the transaction.",
            "nullable": true
          },
          "dental_amount": {
            "type": "integer",
            "description": "The dental amount for the transaction.",
            "nullable": true
          },
          "prescription_amount": {
            "type": "integer",
            "description": "The prescription/RX amount for the transaction.",
            "nullable": true
          },
          "vision_amount": {
            "type": "integer",
            "description": "The vision/optical amount for the transaction.",
            "nullable": true
          }
        }
      },
      "additional_lodging_data": {
        "type": "object",
        "nullable": true,
        "description": "Contains lodging-specific fields for `Authorization` and `Transfer` requests. Optional for lodging MCC transactions (MCC 3501–3999, 7011). Returns `null` for all other transactions.",
        "properties": {
          "check_in_date": {
            "type": "object",
            "nullable": true,
            "description": "The guest's scheduled arrival date.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the check-in date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the check-in date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the check-in date."
              }
            }
          },
          "check_out_date": {
            "type": "object",
            "nullable": true,
            "description": "The guest's scheduled departure date. Must represent a date on or after `check_in_date`.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the check-out date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the check-out date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the check-out date."
              }
            }
          },
          "customer_service_phone": {
            "type": "string",
            "nullable": true,
            "description": "The phone number guests can call for support or inquiries related to their stay."
          },
          "extra_charge_details": {
            "type": "object",
            "nullable": true,
            "description": "Additional charges billed beyond the room rate. Each field represents a specific charge type, in cents.",
            "properties": {
              "restaurant_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "mini_bar_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "laundry_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "other_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "phone_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "gift_shop_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              }
            }
          },
          "hotel_agreement_number": {
            "type": "string",
            "nullable": true,
            "description": "The folio or agreement number associated with the reservation. Max 12 characters; longer values are truncated."
          },
          "is_advance_deposit": {
            "type": "boolean",
            "nullable": true,
            "default": false,
            "description": "Indicates whether the lodging charge is an advance deposit."
          },
          "is_no_show": {
            "type": "boolean",
            "nullable": true,
            "default": false,
            "description": "Set to `true` if the cardholder is being billed for a reserved room that was not occupied."
          },
          "number_of_nights": {
            "type": "integer",
            "nullable": true,
            "description": "The total number of nights for the lodging stay."
          },
          "property_phone": {
            "type": "string",
            "nullable": true,
            "description": "The direct phone number of the lodging property."
          },
          "room_rate": {
            "type": "string",
            "nullable": true,
            "description": "The nightly room rate, in cents."
          },
          "room_tax": {
            "type": "string",
            "nullable": true,
            "description": "The tax amount applied to the room rate, in cents."
          }
        }
      },
      "country": {
        "type": "string",
        "enum": [
          "ABW",
          "AFG",
          "AGO",
          "AIA",
          "ALA",
          "ALB",
          "AND",
          "ARE",
          "ARG",
          "ARM",
          "ASM",
          "ATA",
          "ATF",
          "ATG",
          "AUS",
          "AUT",
          "AZE",
          "BDI",
          "BEL",
          "BEN",
          "BES",
          "BFA",
          "BGD",
          "BGR",
          "BHR",
          "BHS",
          "BIH",
          "BLM",
          "BLR",
          "BLZ",
          "BMU",
          "BOL",
          "BRA",
          "BRB",
          "BRN",
          "BTN",
          "BVT",
          "BWA",
          "CAF",
          "CAN",
          "CCK",
          "CHE",
          "CHL",
          "CHN",
          "CIV",
          "CMR",
          "COD",
          "COG",
          "COK",
          "COL",
          "COM",
          "CPV",
          "CRI",
          "CUB",
          "CUW",
          "CXR",
          "CYM",
          "CYP",
          "CZE",
          "DEU",
          "DJI",
          "DMA",
          "DNK",
          "DOM",
          "DZA",
          "ECU",
          "EGY",
          "ERI",
          "ESH",
          "ESP",
          "EST",
          "ETH",
          "FIN",
          "FJI",
          "FLK",
          "FRA",
          "FRO",
          "FSM",
          "GAB",
          "GBR",
          "GEO",
          "GGY",
          "GHA",
          "GIB",
          "GIN",
          "GLP",
          "GMB",
          "GNB",
          "GNQ",
          "GRC",
          "GRD",
          "GRL",
          "GTM",
          "GUF",
          "GUM",
          "GUY",
          "HKG",
          "HMD",
          "HND",
          "HRV",
          "HTI",
          "HUN",
          "IDN",
          "IMN",
          "IND",
          "IOT",
          "IRL",
          "IRN",
          "IRQ",
          "ISL",
          "ISR",
          "ITA",
          "JAM",
          "JEY",
          "JOR",
          "JPN",
          "KAZ",
          "KEN",
          "KGZ",
          "KHM",
          "KIR",
          "KNA",
          "KOR",
          "KWT",
          "LAO",
          "LBN",
          "LBR",
          "LBY",
          "LCA",
          "LIE",
          "LKA",
          "LSO",
          "LTU",
          "LUX",
          "LVA",
          "MAC",
          "MAF",
          "MAR",
          "MCO",
          "MDA",
          "MDG",
          "MDV",
          "MEX",
          "MHL",
          "MKD",
          "MLI",
          "MLT",
          "MMR",
          "MNE",
          "MNG",
          "MNP",
          "MRT",
          "MSR",
          "MTQ",
          "MUS",
          "MWI",
          "MYS",
          "MYT",
          "NAM",
          "NCL",
          "NER",
          "NFK",
          "NGA",
          "NIC",
          "NIU",
          "NLD",
          "NOR",
          "NPL",
          "NRU",
          "NZL",
          "OMN",
          "PAK",
          "PAN",
          "PCN",
          "PER",
          "PHL",
          "PLW",
          "PNG",
          "POL",
          "PRI",
          "PRK",
          "PRT",
          "PRY",
          "PSE",
          "PYF",
          "QAT",
          "REU",
          "ROU",
          "RUS",
          "RWA",
          "SAU",
          "SDN",
          "SEN",
          "SGP",
          "SGS",
          "SHN",
          "SJM",
          "SLB",
          "SLE",
          "SLV",
          "SMR",
          "SOM",
          "SPM",
          "SRB",
          "SSD",
          "STP",
          "SUR",
          "SVK",
          "SVN",
          "SWE",
          "SWZ",
          "SXM",
          "SYC",
          "SYR",
          "TCA",
          "TCD",
          "TGO",
          "THA",
          "TJK",
          "TKL",
          "TKM",
          "TLS",
          "TON",
          "TTO",
          "TUN",
          "TUR",
          "TUV",
          "TWN",
          "TZA",
          "UGA",
          "UKR",
          "UMI",
          "URY",
          "USA",
          "UZB",
          "VAT",
          "VCT",
          "VEN",
          "VGB",
          "VIR",
          "VNM",
          "VUT",
          "WLF",
          "WSM",
          "XKX",
          "YEM",
          "ZAF",
          "ZMB",
          "ZWE"
        ],
        "nullable": true
      },
      "address": {
        "type": "object",
        "properties": {
          "line1": {
            "type": "string",
            "minLength": 1,
            "description": "First line of the address (max 35 characters).",
            "nullable": true
          },
          "line2": {
            "type": "string",
            "minLength": 1,
            "description": "Second line of the address (max 35 characters).",
            "nullable": true
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "description": "City (max 20 characters).",
            "nullable": true
          },
          "region": {
            "type": "string",
            "minLength": 1,
            "description": "2-letter State code.",
            "nullable": true
          },
          "postal_code": {
            "type": "string",
            "minLength": 1,
            "description": "Zip or Postal code (max 7 characters).",
            "nullable": true
          },
          "country": {
            "$ref": "#/components/schemas/country"
          }
        },
        "required": [
          "city",
          "country",
          "line1",
          "postal_code",
          "region"
        ]
      },
      "additional_motor_vehicle_rental_data": {
        "type": "object",
        "nullable": true,
        "description": "Contains motor vehicle rental-specific fields for `Authorization` and `Transfer` requests. Optional for motor vehicle rental MCC transactions (MCC 3351–3500, 7512). Returns `null` for all other transactions.",
        "properties": {
          "motor_vehicle_rental_agreement_number": {
            "type": "string",
            "nullable": true,
            "description": "The rental agreement or contract reference number for the rental. Max 9 characters; longer values are truncated."
          },
          "customer_service_number": {
            "type": "string",
            "nullable": true,
            "description": "The phone number customers can call for support or inquiries related to their rental."
          },
          "extra_charge_details": {
            "type": "object",
            "nullable": true,
            "description": "Additional charges beyond the base rental rate being billed. Each field represents a specific charge type, in cents.",
            "properties": {
              "extra_mileage_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "fuel_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "insurance_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "late_return_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "one_way_service_fee_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "parking_violation_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              }
            }
          },
          "is_no_show": {
            "type": "boolean",
            "nullable": true,
            "default": false,
            "description": "An indicator that the cardholder is being billed for a reserved vehicle that was not actually rented (that is, a \"no-show\" charge)."
          },
          "number_of_days": {
            "type": "integer",
            "nullable": true,
            "description": "The total number of days for the vehicle rental."
          },
          "rental_rate": {
            "type": "string",
            "nullable": true,
            "description": "The daily rental rate for the vehicle, in cents."
          },
          "renter_name": {
            "type": "string",
            "nullable": true,
            "description": "The name of the person renting the vehicle."
          },
          "pickup_address": {
            "nullable": true,
            "description": "The full address of the rental pickup location.",
            "allOf": [
              {
                "$ref": "#/components/schemas/address"
              }
            ]
          },
          "pickup_date": {
            "type": "object",
            "nullable": true,
            "description": "The scheduled vehicle pickup date.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the pickup date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the pickup date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the pickup date."
              }
            }
          },
          "return_address": {
            "nullable": true,
            "description": "The full address of the vehicle return location.",
            "allOf": [
              {
                "$ref": "#/components/schemas/address"
              }
            ]
          },
          "return_date": {
            "type": "object",
            "nullable": true,
            "description": "The scheduled vehicle return date. Must be on or after `pickup_date`.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the return date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the return date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the return date."
              }
            }
          }
        }
      },
      "customer_reference_number": {
        "type": "string",
        "description": "A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records.",
        "maxLength": 17
      },
      "additional_purchase_data": {
        "type": "object",
        "description": "Additional information about the purchase used for [Level 2 and Level 3 Processing](/guides/online-payments/payment-features/level-2-level-3-processing). Please note that Visa is ending its Level 2 offering in April 2026.",
        "nullable": true,
        "properties": {
          "customer_reference_number": {
            "$ref": "#/components/schemas/customer_reference_number"
          },
          "customs_duty_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The duty in cents on the total purchase amount for the order."
          },
          "destination_country_code": {
            "type": "string",
            "nullable": true,
            "description": "The ISO country code of the order destination."
          },
          "destination_postal_code": {
            "type": "string",
            "nullable": true,
            "description": "The postal code of the order destination (10 characters).",
            "maxLength": 10
          },
          "discount_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The amount in cents of the discount for the order. You must include this field to qualify for Level 3 interchange benefits. Even if the value is (0), you should pass the field to qualify for Level 3."
          },
          "invoice_reference_number": {
            "type": "string",
            "nullable": true,
            "description": "The order's invoice number (max 15 characters).",
            "maxLength": 15
          },
          "order_date": {
            "type": "object",
            "nullable": true,
            "properties": {
              "day": {
                "type": "integer",
                "description": "Day of purchase (between 1 and 31)."
              },
              "month": {
                "type": "integer",
                "description": "Month of purchase (between 1 and 12)."
              },
              "year": {
                "type": "integer",
                "description": "Year of purchase (4-digit).",
                "minimum": 1990
              }
            }
          },
          "sales_tax": {
            "type": "integer",
            "nullable": true,
            "description": "- Total aggregate tax amount in cents for the entire purchase. Field is automatically calculated if you pass in the itemized tax amounts.\n- For non-taxable transactions either set `sales_tax` to 0 or omit from payload and also set `tax_exempt` to **True**.\n- Request must align so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`.\n- For Visa, this field no longer qualifies for lower interchange after April 17, 2026. Include `item_data` for Level 3 processing."
          },
          "sales_tax_finix_generated": {
            "type": "integer",
            "description": "The sales tax amount in cents Finix calculated from the `item_data` line items.",
            "nullable": true
          },
          "ship_from_postal_code": {
            "type": "string",
            "nullable": true,
            "description": "The postal code from where order is shipped (10 characters).",
            "maxLength": 10
          },
          "shipping_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The shipping cost in cents for the order.\n"
          },
          "tax_exempt": {
            "type": "boolean",
            "description": "- For tax exempt purchases set to **True**.\n- If set to **True**, request can't include `sales_tax`."
          },
          "item_data": {
            "type": "array",
            "description": "Additional information about the transaction. Used for Level 2 and Level 3 Processing.",
            "items": {
              "type": "object",
              "properties": {
                "amount_excluding_sales_tax": {
                  "type": "integer",
                  "description": "- Total cost of the line item in cents, excluding tax.\n- Must align with `sales_tax` so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`."
                },
                "amount_including_sales_tax": {
                  "type": "integer",
                  "description": "- Total cost of the line item in cents, including tax.\n- Must align with `sales_tax` so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`."
                },
                "commodity_code": {
                  "description": "A commodity code is a numeric code representing a particular product or service as defined by the National Institute of Governmental Purchasing. The code can be 3, 5, 7, or 11 digits in length. The longer the code the more granular the description of the product/service. (max 12 characters).",
                  "type": "string",
                  "maxLength": 12
                },
                "cost_per_unit": {
                  "type": "integer",
                  "description": "The price in cents, excluding tax, of one unit of the item purchased."
                },
                "item_description": {
                  "type": "string",
                  "description": "Required when `item_data` is supplied (max 25 characters).",
                  "maxLength": 25
                },
                "item_discount_amount": {
                  "type": "integer",
                  "description": "The item discount amount in cents. You must include this field to qualify for Level 3 interchange benefits. Even if the value is (0), you should pass the field to qualify for Level 3."
                },
                "merchant_product_code": {
                  "type": "string",
                  "description": "Merchant defined product code (max 12 characters).",
                  "maxLength": 12
                },
                "quantity": {
                  "type": "number",
                  "description": "The number of items purchased. Must be greater than 0.",
                  "minimum": 1,
                  "maximum": 99
                },
                "unit_of_measure": {
                  "type": "string",
                  "description": "The unit of measure of the purchased item (max 3 characters).",
                  "maxLength": 3
                },
                "sales_tax_amount": {
                  "type": "integer",
                  "description": "The sales tax amount in cents for the line item."
                },
                "sales_tax_rate": {
                  "type": "number",
                  "description": "The sales tax rate for the line item as a decimal (e.g., 0.25 equals 25%).",
                  "example": 0.25
                }
              }
            }
          }
        }
      },
      "amount": {
        "type": "integer",
        "description": "The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).",
        "example": 5000,
        "format": "int64"
      },
      "tags": {
        "type": "object",
        "title": "tags",
        "additionalProperties": true,
        "description": "Include up to 50 `key: value` pairs to annotate requests with custom metadata.\n- Maximum character length for individual `keys` is 40.\n- Maximum character length for individual `values` is 500.\n(For example, `order_number: 25`, `item_type: produce`, `department: sales`)",
        "nullable": true
      },
      "currency": {
        "type": "string",
        "description": "ISO 4217 3-letter currency code.",
        "enum": [
          "CAD",
          "USD"
        ]
      },
      "created_via_transfers_authorizations": {
        "type": "string",
        "description": "Gives more information about the product flow that was used to create the resource. Finix retains the right to add additional enums for this field without it being a breaking change.",
        "default": "UNKNOWN",
        "enum": [
          "CARD_PRESENT_ANDROID_APP",
          "CARD_PRESENT_ANDROID_APP_MANUAL_ENTRY",
          "CARD_PRESENT_ANDROID_D135_SDK",
          "CARD_PRESENT_DEVICE_READER_SDK",
          "CARD_PRESENT_IOS_APP",
          "CARD_PRESENT_IOS_APP_MANUAL_ENTRY",
          "CARD_PRESENT_IOS_D135_SDK",
          "CARD_PRESENT_IOS_TAP_TO_PAY",
          "CARD_PRESENT_IOS_TAP_TO_PAY_SDK",
          "CARD_PRESENT_SEMI_INTEGRATED_API",
          "CARD_PRESENT_STANDALONE",
          "CARD_PRESENT_STANDALONE_MANUAL_ENTRY",
          "CHECKOUT_FORM",
          "CYBERSOURCE",
          "DEVICE_ORDER",
          "PAYMENT_LINK",
          "PAYOUT_LINK",
          "PLUGIN_ADMOJI",
          "PLUGIN_CHECKOUT_CHAMP",
          "PLUGIN_FYNTEK",
          "PLUGIN_GAMBLE_ID",
          "PLUGIN_GAMMA_SWEEP",
          "PLUGIN_GR4VY",
          "PLUGIN_HYPERSWITCH",
          "PLUGIN_LACORE",
          "PLUGIN_PAYSIGHT",
          "PLUGIN_PRYZR",
          "PLUGIN_SERVMAN",
          "PLUGIN_SOAP_PAY",
          "PLUGIN_STICKYIO",
          "PLUGIN_TAGADA",
          "PLUGIN_WOO_COMMERCE",
          "PLUGIN_VRIO",
          "SUBSCRIPTION",
          "UNKNOWN",
          "VIRTUAL_TERMINAL"
        ]
      },
      "failure_code": {
        "type": "string",
        "description": "The code of the failure so the decline can be handled programmatically. For more info on how to handle the failure, see [Failure Codes](/additional-resources/developers/implementation-and-testing/failure-codes).",
        "nullable": true
      },
      "failure_message": {
        "type": "string",
        "description": "A human-readable description of why the transaction was declined. This will also include a suggestion on how to complete the payment.",
        "nullable": true
      },
      "fee_transfer": {
        "type": "integer",
        "format": "int64",
        "description": "The minimum amount of the `Transfer` you'd like to collect as your fee in cents. Defaults to zero (must be less than or equal to the `amount`).\n- If the fees applied by the 'Fee Profile' are ***higher*** than the value passed in 'fee', 'fee' will not be applied and have no effect.\n- If the fees applied by the 'Fee Profile' are ***lower*** than the value passed in 'fee', an additional fee is be applied, in addition to the fees generated by the `Fee Profile`.\n    - The additional fee is equal to the difference between the value passed in 'fee' and the fees generated by the `Fee Profile`."
      },
      "funds_flow_type": {
        "type": "string",
        "description": "The type of disbursement to perform. Defaults to `GENERAL_PAYOUT`.\n",
        "enum": [
          "GENERAL_PAYOUT",
          "ME_TO_ME",
          "GOVERNMENT"
        ],
        "nullable": true
      },
      "idempotency_id": {
        "type": "string",
        "description": "Pass any randomly generated or internal ID to [idempotently](/api/section/idempotent-requests) identify `Transfers`, `Authorizations`, or refund requests.",
        "nullable": true
      },
      "statement_descriptor": {
        "type": "string",
        "maxLength": 20,
        "nullable": true,
        "description": "The description of the `Merchant` that appears on the buyer's bank or card statement."
      },
      "application_link": {
        "type": "object",
        "description": "Link to the `Application` the request was made under.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "self": {
        "type": "object",
        "description": "Link to the resource that was used in the request.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "transfer": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/id"
          },
          "created_at": {
            "$ref": "#/components/schemas/created_at"
          },
          "updated_at": {
            "$ref": "#/components/schemas/updated_at"
          },
          "3d_secure_session": {
            "type": "string",
            "nullable": true,
            "description": "The ID of the `3D Secure Session` that authenticated the buyer. This field is `null` when the payment was not authenticated with a `3D Secure Session`.",
            "example": "3d_secure_session_f3fG3Zj8K958MTP5vpXAXX"
          },
          "additional_buyer_charges": {
            "description": "Details about any [Buyer Charges](../../../../guides/online-payments/payment-features/buyer-charges) included in the `Transfer`. The buyer charges are mutually exclusive.\n",
            "allOf": [
              {
                "$ref": "#/components/schemas/additional_buyer_charges"
              }
            ]
          },
          "additional_healthcare_data": {
            "$ref": "#/components/schemas/additional_healthcare_data"
          },
          "additional_lodging_data": {
            "$ref": "#/components/schemas/additional_lodging_data"
          },
          "additional_motor_vehicle_rental_data": {
            "$ref": "#/components/schemas/additional_motor_vehicle_rental_data"
          },
          "additional_purchase_data": {
            "$ref": "#/components/schemas/additional_purchase_data"
          },
          "address_verification": {
            "type": "string",
            "description": "Details the results of the address verification checks.",
            "nullable": true,
            "enum": [
              "POSTAL_CODE_AND_STREET_MATCH",
              "STREET_MATCH",
              "POSTAL_CODE_MATCH",
              "NO_ADDRESS",
              "NO_MATCH",
              "NOT_SUPPORTED",
              "UNKNOWN"
            ]
          },
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "amount_requested": {
            "type": "integer",
            "format": "int64",
            "description": "The `amount` that was requested to get debited from the `source` when the transaction was created, in cents (e.g., `100` = $1.00).",
            "example": 100
          },
          "application": {
            "type": "string",
            "minLength": 1,
            "description": "ID of the `Application` associated with the resource."
          },
          "bank_return_details": {
            "type": "object",
            "description": "Details about a transfer that was returned and was unable to be processed. Only present when `state` is `RETURNED`",
            "nullable": true,
            "properties": {
              "reason_code": {
                "type": "string",
                "description": "Return response code from the bank."
              },
              "reason_message": {
                "type": "string",
                "description": "Detailed message explaining reason for the return."
              },
              "reason_title": {
                "type": "string",
                "description": "Short message categorizing reason for the return."
              }
            }
          },
          "card_present_details": {
            "type": "object",
            "description": "Details needed to process card present transactions.",
            "nullable": true,
            "properties": {
              "approval_code": {
                "type": "string",
                "description": "Unique ID used to identify the approval of the `Transfer`.",
                "nullable": true
              },
              "brand": {
                "type": "string",
                "description": "The brand of the card saved in the `Payment Instrument`.",
                "nullable": true
              },
              "emv_data": {
                "type": "object",
                "description": "Encrypted card data used to process the transaction.",
                "nullable": true,
                "properties": {
                  "application_identifier": {
                    "type": "string",
                    "description": "ID of the application used in the transaction. Tag 9F06 from the EMVCo standard.",
                    "nullable": true
                  },
                  "application_label": {
                    "type": "string",
                    "description": "EMV application label. Tag 50 from the EMVCo standard.",
                    "nullable": true
                  },
                  "application_preferred_name": {
                    "type": "string",
                    "description": "EMV application label with formatting (if provided). Tag 9F12 from the EMVCo standard.",
                    "nullable": true
                  },
                  "application_transaction_counter": {
                    "type": "string",
                    "description": "Transaction number for the EMV application. Tag 9F36 from the EMVCo standard.",
                    "nullable": true
                  },
                  "cryptogram": {
                    "type": "string",
                    "description": "Cryptogram returned by the card. Tag 9F26 of the EMVCo standard.",
                    "nullable": true
                  },
                  "issuer_code_table_index": {
                    "type": "string",
                    "description": "The alphabet code table (according to ISO 8859) used by the EMV application (if provided). Tag 9F11.",
                    "nullable": true
                  },
                  "network_emv_response": {
                    "type": "string",
                    "description": "EMV response data returned by the card network.",
                    "nullable": true
                  },
                  "pin_verified": {
                    "type": "boolean",
                    "description": "Whether the cardholder's PIN number was verified."
                  },
                  "tags": {
                    "$ref": "#/components/schemas/tags"
                  }
                }
              },
              "entry_mode": {
                "type": "string",
                "description": "Details of the card payment method used to process the transaction.\n\nThe possible enums are:\n\n- UNKNOWN - The method by which the payment card was used is unknown.\n- SWIPED - The card was swiped through a POS terminal.\n- CONTACTLESS - The payment was made by tapping a card on a POS terminal.\n- CHIP_ENTRY - The payment card was inserted into a card reader.\n",
                "enum": [
                  "UNKNOWN",
                  "SWIPED",
                  "CONTACTLESS",
                  "CHIP_ENTRY"
                ],
                "nullable": true
              },
              "masked_account_number": {
                "type": "string",
                "description": "Last four digits of the bank account number.",
                "nullable": true
              },
              "name": {
                "type": "string",
                "description": "The name of the bank account or card owner.",
                "nullable": true
              },
              "digital_signature_file_id": {
                "type": "string",
                "description": "The ID of the file containing the digital signature captured during the transaction. If a signature was not collected, this field returns `null`.",
                "nullable": true
              },
              "payment_type": {
                "type": "string",
                "description": "The type of `Payment Instrument` used in the transaction (or the original payment).",
                "nullable": true
              }
            }
          },
          "currency": {
            "$ref": "#/components/schemas/currency"
          },
          "created_via": {
            "$ref": "#/components/schemas/created_via_transfers_authorizations"
          },
          "destination": {
            "type": "string",
            "description": "ID of the `Payment Instrument` where funds will be sent.",
            "nullable": true
          },
          "device": {
            "type": "string",
            "description": "The ID of the `Device` resource the `Transfer` was created under."
          },
          "externally_funded": {
            "type": "string",
            "description": "Details if the `Transfer` will be settled externally by card processors."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp indicating when a held refund expires. Only returned for reversals created with refund holds enabled. A refund that can't be covered by this time fails with `failure_code: REFUND_EXPIRED`. For more information, see [Pending refunds](/guides/after-the-payment/refunds/pending-refunds).",
            "nullable": true
          },
          "failure_code": {
            "$ref": "#/components/schemas/failure_code"
          },
          "failure_message": {
            "$ref": "#/components/schemas/failure_message"
          },
          "fee": {
            "$ref": "#/components/schemas/fee_transfer"
          },
          "fee_profile": {
            "type": "string",
            "description": "The ID of the `Fee Profile` that will be used for calculating fees for this transfer."
          },
          "funds_flow_type": {
            "$ref": "#/components/schemas/funds_flow_type"
          },
          "idempotency_id": {
            "$ref": "#/components/schemas/idempotency_id"
          },
          "ip_address_details": {
            "type": "object",
            "description": "Always returns `null`.",
            "nullable": true
          },
          "merchant": {
            "type": "string",
            "description": "The ID of the `Merchant` resource the `Transfer` was created under.",
            "example": "MUxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "merchant_identity": {
            "type": "string",
            "example": "IDxxxxxxxxxxxxxxxxxxxxxxxx",
            "description": "The ID of `Identity` resource used by the `Merchant` the `Transfer` was created under."
          },
          "messages": {
            "type": "array",
            "description": "A list of messages that provides additional details.",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "network_details": {
            "type": "object",
            "nullable": true,
            "description": "Contains network-specific fields used by issuers to identify transactions.",
            "properties": {
              "brand": {
                "type": "string",
                "description": "Card brand associated with the saved payment instrument.",
                "example": "VISA"
              },
              "authorization_code": {
                "type": "string",
                "description": "Code returned by the issuing bank when a transaction is authorized.",
                "example": 840735
              },
              "acquirer_reference_number": {
                "type": "string",
                "description": "Unique identifier banks use to trace chargebacks or refunds. Available only for Mastercard transactions; otherwise returns `null`.",
                "nullable": true,
                "example": 521600805857
              }
            }
          },
          "operation_key": {
            "type": "string",
            "enum": [
              "CARD_NOT_PRESENT_CAPTURE",
              "CARD_NOT_PRESENT_REFUND",
              "CARD_NOT_PRESENT_SALE",
              "CARD_NOT_PRESENT_UNREFERENCED_REFUND",
              "CARD_PRESENT_AUTHORIZATION",
              "CARD_PRESENT_DEBIT",
              "CARD_PRESENT_SALE",
              "CARD_PRESENT_UNREFERENCED_REFUND",
              "INSTANT_APPLICATION_FUNDING_PULL_FROM_ACH",
              "INSTANT_APPLICATION_FUNDING_PULL_FROM_CARD",
              "INSTANT_APPLICATION_FUNDING_PULL_FROM_FED_NOW",
              "INSTANT_APPLICATION_FUNDING_PULL_FROM_SAME_DAY_ACH",
              "INSTANT_APPLICATION_FUNDING_PUSH_TO_ACH",
              "INSTANT_APPLICATION_FUNDING_PUSH_TO_CARD",
              "INSTANT_APPLICATION_FUNDING_PUSH_TO_FED_NOW",
              "INSTANT_APPLICATION_FUNDING_PUSH_TO_SAME_DAY_ACH",
              "INSTANT_MERCHANT_FUNDING_PULL_FROM_ACH",
              "INSTANT_MERCHANT_FUNDING_PULL_FROM_FED_NOW",
              "INSTANT_MERCHANT_FUNDING_PULL_FROM_SAME_DAY_ACH",
              "INSTANT_MERCHANT_FUNDING_PUSH_TO_ACH",
              "INSTANT_MERCHANT_FUNDING_PUSH_TO_CARD",
              "INSTANT_MERCHANT_FUNDING_PUSH_TO_FED_NOW",
              "INSTANT_MERCHANT_FUNDING_PUSH_TO_SAME_DAY_ACH",
              "MERCHANT_CREDIT_ADJUSTMENT",
              "MERCHANT_DEBIT_ADJUSTMENT",
              "PULL_FROM_ACH",
              "PULL_FROM_CARD",
              "PULL_FROM_SAME_DAY_ACH",
              "PUSH_TO_ACH",
              "PUSH_TO_CARD",
              "PUSH_TO_SAME_DAY_ACH",
              "REFUND_MERCHANT_CREDIT_ADJUSTMENT",
              "REFUND_MERCHANT_DEBIT_ADJUSTMENT",
              "SALE",
              "STANDARD_APPLICATION_FUNDING_PULL_FROM_ACH",
              "STANDARD_APPLICATION_FUNDING_PULL_FROM_CARD",
              "STANDARD_APPLICATION_FUNDING_PULL_FROM_SAME_DAY_ACH",
              "STANDARD_APPLICATION_FUNDING_PUSH_TO_ACH",
              "STANDARD_APPLICATION_FUNDING_PUSH_TO_CARD",
              "STANDARD_APPLICATION_FUNDING_PUSH_TO_SAME_DAY_ACH",
              "STANDARD_MERCHANT_FUNDING_PULL_FROM_ACH",
              "STANDARD_MERCHANT_FUNDING_PULL_FROM_CARD",
              "STANDARD_MERCHANT_FUNDING_PULL_FROM_SAME_DAY_ACH",
              "STANDARD_MERCHANT_FUNDING_PUSH_TO_ACH",
              "STANDARD_MERCHANT_FUNDING_PUSH_TO_CARD",
              "STANDARD_MERCHANT_FUNDING_PUSH_TO_SAME_DAY_ACH",
              "UNREFERENCED_REFUND"
            ],
            "description": "The operation performed in the transaction. `REFUND_MERCHANT_DEBIT_ADJUSTMENT` and `REFUND_MERCHANT_CREDIT_ADJUSTMENT` are created by Finix for [refund holds](/guides/after-the-payment/refunds/pending-refunds) and cannot be passed in requests.",
            "nullable": true
          },
          "parent_transfer": {
            "type": "string",
            "description": "ID of the original parent `Transfer`. Only present when `type` is `REVERSAL`.",
            "nullable": true
          },
          "parent_transfer_trace_id": {
            "type": "string",
            "description": "The `trace_id` of the original parent `Transfer`. Only present when `type` is `REVERSAL`.",
            "nullable": true
          },
          "processed_at": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp of when the `Transfer` was processed.",
            "nullable": true
          },
          "pull_transfer_id": {
            "type": "string",
            "nullable": true,
            "description": "The ID of the corresponding pull `Transfer` linked in a `ME_TO_ME` transaction."
          },
          "raw": {
            "description": "Raw response from the processor.",
            "anyOf": [
              {
                "type": "object",
                "nullable": true
              },
              {
                "type": "string",
                "nullable": true
              }
            ]
          },
          "ready_to_settle_at": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp indicating when the `Transfer` is ready to be settled.",
            "nullable": true
          },
          "receipt_last_printed_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the receipt was last printed.",
            "nullable": true
          },
          "security_code_verification": {
            "type": "string",
            "nullable": true,
            "description": "Details the results of the Card Verification Code check.",
            "enum": [
              "MATCHED",
              "UNKNOWN",
              "UNMATCHED"
            ]
          },
          "source": {
            "type": "string",
            "description": "The ID of the `Payment Instrument` that will be debited and performing the `Transfer`.",
            "nullable": true
          },
          "split_transfers": {
            "type": "array",
            "description": "Array containing the resource IDs of the `Split Transfers` generated from the `Transfer`.\n\nFor standard split transactions, this contains IDs of `Split Transfers` created from the parent `Transfer`.\n\nFor [dispute adjustment transfers](/api/disputes/listdisputesadjustments) on split transactions:\n- When a `MERCHANT_DEBIT` or `MERCHANT_CREDIT` adjustment `Transfer` is created for a [Dispute](/api/disputes) on a split transaction, this array contains the IDs of `Split Transfers` created for each participant.\n- The `Split Transfers` are created proportionally based on each merchant's share of the original sale.\n\nFor more information, see [Split Transactions - Disputes](../../../../guides/online-payments/payment-features/split-transactions#disputes).\n",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "state": {
            "type": "string",
            "enum": [
              "CANCELED",
              "PENDING",
              "FAILED",
              "SUCCEEDED",
              "UNKNOWN",
              "RETURNED"
            ],
            "description": "The status of the `Transfer`."
          },
          "statement_descriptor": {
            "$ref": "#/components/schemas/statement_descriptor"
          },
          "subtype": {
            "type": "string",
            "description": "Additional information describing the `payment_type`.\n\nFor [dispute adjustment transfers](/api/disputes/listdisputesadjustments) (`type: DISPUTE`):\n- `MERCHANT_DEBIT`: Funds are pulled from the merchant(s) when a chargeback occurs. For split transactions, this creates `Split Transfers` with `type: DISPUTE_MERCHANT_DEBIT`.\n- `MERCHANT_CREDIT`: Funds are returned to the merchant(s) when a `Dispute` is ruled in their favor. For split transactions, this creates `Split Transfers` with `type: DISPUTE_MERCHANT_CREDIT`.\n\nFor [refund hold](/guides/after-the-payment/refunds/pending-refunds) adjustment transfers:\n- `REFUND_MERCHANT_DEBIT_ADJUSTMENT`: Funds are pulled from the merchant to cover a held refund.\n- `REFUND_MERCHANT_CREDIT_ADJUSTMENT`: Funds are returned to the merchant when the held refund is submitted or expires.\n",
            "enum": [
              "API",
              "DISPUTE",
              "MERCHANT_CREDIT",
              "MERCHANT_CREDIT_ADJUSTMENT",
              "MERCHANT_DEBIT",
              "MERCHANT_DEBIT_ADJUSTMENT",
              "PLATFORM_CREDIT",
              "PLATFORM_CREDIT_ADJUSTMENT",
              "PLATFORM_DEBIT",
              "PLATFORM_DEBIT_ADJUSTMENT",
              "REFUND_MERCHANT_CREDIT_ADJUSTMENT",
              "REFUND_MERCHANT_DEBIT_ADJUSTMENT",
              "SETTLEMENT_MERCHANT",
              "SETTLEMENT_NOOP",
              "SETTLEMENT_PARTNER",
              "SETTLEMENT_PLATFORM",
              "SPLIT_PAYOUT",
              "SPLIT_PAYOUT_ADJUSTMENT",
              "SYSTEM"
            ]
          },
          "supplemental_fee": {
            "type": "string",
            "description": "Amount in cents for which an additional fee will be created in addition to any fees created from the assigned fee profile.",
            "nullable": true
          },
          "tags": {
            "$ref": "#/components/schemas/tags"
          },
          "tip_amount": {
            "type": "integer",
            "description": "The tip amount included in the total amount.",
            "nullable": true
          },
          "trace_id": {
            "type": "string",
            "description": "Trace ID of the `Transfer`. The processor sends back the `trace_id` so you can track the `Transfer` end-to-end.",
            "nullable": true
          },
          "type": {
            "type": "string",
            "description": "Type of `Transfer`.",
            "enum": [
              "DEBIT",
              "CREDIT",
              "REVERSAL",
              "ADJUSTMENT",
              "DISPUTE",
              "RESERVE",
              "SETTLEMENT",
              "UNKNOWN"
            ]
          },
          "third_party_details": {
            "type": "object",
            "description": "Details about the third-party processor associated with the `Transfer`.",
            "nullable": true,
            "properties": {
              "external_trace_id": {
                "type": "string",
                "description": "The trace ID returned by the third-party processor used to identify the `Transfer`.",
                "nullable": true
              },
              "type": {
                "type": "string",
                "description": "The name of the third-party processor associated with the `Transfer`.",
                "nullable": true,
                "enum": [
                  "CYBERSOURCE"
                ]
              }
            }
          },
          "_links": {
            "type": "object",
            "properties": {
              "application": {
                "$ref": "#/components/schemas/application_link"
              },
              "destination": {
                "type": "object",
                "description": "Link to the `Payment Instrument` where funds are getting sent.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "device": {
                "type": "object",
                "description": "Link to the `Device` the request was made under.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "disputes": {
                "type": "object",
                "description": "Link to the `Dispute` the request was made under.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "fee_profile": {
                "type": "object",
                "description": "Link to the `fee_profile` the request was made under.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "fees": {
                "type": "object",
                "description": "Link to the `fees` the request is associated with.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "merchant_identity": {
                "type": "object",
                "description": "Link to the `Identity` the `Merchant` was created under and the `Transfer` was submitted with.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "payment_instruments": {
                "type": "object",
                "description": "Link to the `Payment Instrument` associated with the Transfer.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "disputed_transfer": {
                "type": "object",
                "description": "Link to the `Transfer` the `Dispute` is about.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "parent": {
                "type": "object",
                "description": "Link to the original resource that was used in the request.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "reversals": {
                "type": "object",
                "description": "Link to the `reversals` associated with the `Transfer`.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "self": {
                "$ref": "#/components/schemas/self"
              },
              "source": {
                "type": "object",
                "description": "Link to the `Payment Instrument` the `Transfer` was created under.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## Create an Authorization with Level 2 processing

Send a POST /authorizations request and include the required fields for Level 2 processing.

### Level 2 Fields

Include the following `additional_purchase_data` fields:

| Field | API Field | Type | Description |
|  --- | --- | --- | --- |
| **Customer Reference Number** | `customer_reference_number` | *string*, **required** | A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records. (max `17` characters) |
| **Sales Tax** | `sales_tax` | *integer*, **required** | Total aggregate tax amount in cents for the entire purchase. Field is automatically calculated if you pass in the itemized tax amounts. For non-taxable transactions either set `sales_tax` to `0` or omit from payload and also set `tax_exempt` to `true`.` |


### Request

```shell
curl https://finix.sandbox-payments-api.com/authorizations \
  -H "Content-Type: application/json" \
  -H 'Finix-Version: 2022-02-01' \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  -d '{
    "additional_purchase_data": {
      "customer_reference_number": "PO-2024-3842",
      "sales_tax": 200
    },
    "amount": 10000,
    "currency": "USD",
    "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
    "source": "PIs3rzrjP9orEjBwtJjhxEjL"
  }'
```

### Response

A successful request returns a `201 Created` status code and includes an Authorization resource with Level 2 processing details:

Example
Authorization - Level 2 Processing
```json Authorization - Level 2 Processing
{
  "id": "AUpkHPontypnra6ixQ6nKaCD",
  "created_at": "2026-09-25T20:05:02.19Z",
  "updated_at": "2026-09-25T20:05:02.19Z",
  "3d_secure_session": null,
  "3ds_redirect_url": null,
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_lodging_data": null,
  "additional_motor_vehicle_rental_data": null,
  "additional_purchase_data": {
    "customer_reference_number": "PO-2024-3842", // [!code highlight]
    "customs_duty_amount": null,
    "destination_country_code": null,
    "destination_postal_code": null,
    "discount_amount": null,
    "invoice_reference_number": null,
    "order_date": null,
    "sales_tax": 200, // [!code highlight]
    "sales_tax_finix_generated": null,
    "ship_from_postal_code": null,
    "shipping_amount": null,
    "tax_exempt": false,
    "item_data": []
  },
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "amount": 10000,
  "amount_requested": 10000,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_via": "UNKNOWN",
  "currency": "USD",
  "expires_at": "2026-10-02T20:05:02.19Z",
  "failure_code": null,
  "failure_message": null,
  "idempotency_id": null,
  "ip_address_details": null,
  "is_void": false,
  "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
  "merchant_identity": "IDjvxGeXBLKH1V9YnWm1CS4n",
  "messages": [],
  "network_details": {
    "brand": "MASTERCARD",
    "authorization_code": "899854"
  },
  "raw": null,
  "receipt_last_printed_at": null,
  "security_code_verification": "MATCHED",
  "source": "PIs3rzrjP9orEjBwtJjhxEjL",
  "state": "SUCCEEDED",
  "supplemental_fee": null,
  "tags": {},
  "trace_id": "0e189372-9f27-4475-80f0-9e755be33d3b",
  "transfer": null,
  "void_state": "UNATTEMPTED",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/authorizations/AUpkHPontypnra6ixQ6nKaCD"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n"
    }
  }
}
```

API Definition
```json
{
  "$ref": "#/components/schemas/authorization",
  "components": {
    "schemas": {
      "created_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was created."
      },
      "updated_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was last updated."
      },
      "additional_lodging_data": {
        "type": "object",
        "nullable": true,
        "description": "Contains lodging-specific fields for `Authorization` and `Transfer` requests. Optional for lodging MCC transactions (MCC 3501–3999, 7011). Returns `null` for all other transactions.",
        "properties": {
          "check_in_date": {
            "type": "object",
            "nullable": true,
            "description": "The guest's scheduled arrival date.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the check-in date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the check-in date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the check-in date."
              }
            }
          },
          "check_out_date": {
            "type": "object",
            "nullable": true,
            "description": "The guest's scheduled departure date. Must represent a date on or after `check_in_date`.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the check-out date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the check-out date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the check-out date."
              }
            }
          },
          "customer_service_phone": {
            "type": "string",
            "nullable": true,
            "description": "The phone number guests can call for support or inquiries related to their stay."
          },
          "extra_charge_details": {
            "type": "object",
            "nullable": true,
            "description": "Additional charges billed beyond the room rate. Each field represents a specific charge type, in cents.",
            "properties": {
              "restaurant_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "mini_bar_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "laundry_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "other_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "phone_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "gift_shop_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              }
            }
          },
          "hotel_agreement_number": {
            "type": "string",
            "nullable": true,
            "description": "The folio or agreement number associated with the reservation. Max 12 characters; longer values are truncated."
          },
          "is_advance_deposit": {
            "type": "boolean",
            "nullable": true,
            "default": false,
            "description": "Indicates whether the lodging charge is an advance deposit."
          },
          "is_no_show": {
            "type": "boolean",
            "nullable": true,
            "default": false,
            "description": "Set to `true` if the cardholder is being billed for a reserved room that was not occupied."
          },
          "number_of_nights": {
            "type": "integer",
            "nullable": true,
            "description": "The total number of nights for the lodging stay."
          },
          "property_phone": {
            "type": "string",
            "nullable": true,
            "description": "The direct phone number of the lodging property."
          },
          "room_rate": {
            "type": "string",
            "nullable": true,
            "description": "The nightly room rate, in cents."
          },
          "room_tax": {
            "type": "string",
            "nullable": true,
            "description": "The tax amount applied to the room rate, in cents."
          }
        }
      },
      "country": {
        "type": "string",
        "enum": [
          "ABW",
          "AFG",
          "AGO",
          "AIA",
          "ALA",
          "ALB",
          "AND",
          "ARE",
          "ARG",
          "ARM",
          "ASM",
          "ATA",
          "ATF",
          "ATG",
          "AUS",
          "AUT",
          "AZE",
          "BDI",
          "BEL",
          "BEN",
          "BES",
          "BFA",
          "BGD",
          "BGR",
          "BHR",
          "BHS",
          "BIH",
          "BLM",
          "BLR",
          "BLZ",
          "BMU",
          "BOL",
          "BRA",
          "BRB",
          "BRN",
          "BTN",
          "BVT",
          "BWA",
          "CAF",
          "CAN",
          "CCK",
          "CHE",
          "CHL",
          "CHN",
          "CIV",
          "CMR",
          "COD",
          "COG",
          "COK",
          "COL",
          "COM",
          "CPV",
          "CRI",
          "CUB",
          "CUW",
          "CXR",
          "CYM",
          "CYP",
          "CZE",
          "DEU",
          "DJI",
          "DMA",
          "DNK",
          "DOM",
          "DZA",
          "ECU",
          "EGY",
          "ERI",
          "ESH",
          "ESP",
          "EST",
          "ETH",
          "FIN",
          "FJI",
          "FLK",
          "FRA",
          "FRO",
          "FSM",
          "GAB",
          "GBR",
          "GEO",
          "GGY",
          "GHA",
          "GIB",
          "GIN",
          "GLP",
          "GMB",
          "GNB",
          "GNQ",
          "GRC",
          "GRD",
          "GRL",
          "GTM",
          "GUF",
          "GUM",
          "GUY",
          "HKG",
          "HMD",
          "HND",
          "HRV",
          "HTI",
          "HUN",
          "IDN",
          "IMN",
          "IND",
          "IOT",
          "IRL",
          "IRN",
          "IRQ",
          "ISL",
          "ISR",
          "ITA",
          "JAM",
          "JEY",
          "JOR",
          "JPN",
          "KAZ",
          "KEN",
          "KGZ",
          "KHM",
          "KIR",
          "KNA",
          "KOR",
          "KWT",
          "LAO",
          "LBN",
          "LBR",
          "LBY",
          "LCA",
          "LIE",
          "LKA",
          "LSO",
          "LTU",
          "LUX",
          "LVA",
          "MAC",
          "MAF",
          "MAR",
          "MCO",
          "MDA",
          "MDG",
          "MDV",
          "MEX",
          "MHL",
          "MKD",
          "MLI",
          "MLT",
          "MMR",
          "MNE",
          "MNG",
          "MNP",
          "MRT",
          "MSR",
          "MTQ",
          "MUS",
          "MWI",
          "MYS",
          "MYT",
          "NAM",
          "NCL",
          "NER",
          "NFK",
          "NGA",
          "NIC",
          "NIU",
          "NLD",
          "NOR",
          "NPL",
          "NRU",
          "NZL",
          "OMN",
          "PAK",
          "PAN",
          "PCN",
          "PER",
          "PHL",
          "PLW",
          "PNG",
          "POL",
          "PRI",
          "PRK",
          "PRT",
          "PRY",
          "PSE",
          "PYF",
          "QAT",
          "REU",
          "ROU",
          "RUS",
          "RWA",
          "SAU",
          "SDN",
          "SEN",
          "SGP",
          "SGS",
          "SHN",
          "SJM",
          "SLB",
          "SLE",
          "SLV",
          "SMR",
          "SOM",
          "SPM",
          "SRB",
          "SSD",
          "STP",
          "SUR",
          "SVK",
          "SVN",
          "SWE",
          "SWZ",
          "SXM",
          "SYC",
          "SYR",
          "TCA",
          "TCD",
          "TGO",
          "THA",
          "TJK",
          "TKL",
          "TKM",
          "TLS",
          "TON",
          "TTO",
          "TUN",
          "TUR",
          "TUV",
          "TWN",
          "TZA",
          "UGA",
          "UKR",
          "UMI",
          "URY",
          "USA",
          "UZB",
          "VAT",
          "VCT",
          "VEN",
          "VGB",
          "VIR",
          "VNM",
          "VUT",
          "WLF",
          "WSM",
          "XKX",
          "YEM",
          "ZAF",
          "ZMB",
          "ZWE"
        ],
        "nullable": true
      },
      "address": {
        "type": "object",
        "properties": {
          "line1": {
            "type": "string",
            "minLength": 1,
            "description": "First line of the address (max 35 characters).",
            "nullable": true
          },
          "line2": {
            "type": "string",
            "minLength": 1,
            "description": "Second line of the address (max 35 characters).",
            "nullable": true
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "description": "City (max 20 characters).",
            "nullable": true
          },
          "region": {
            "type": "string",
            "minLength": 1,
            "description": "2-letter State code.",
            "nullable": true
          },
          "postal_code": {
            "type": "string",
            "minLength": 1,
            "description": "Zip or Postal code (max 7 characters).",
            "nullable": true
          },
          "country": {
            "$ref": "#/components/schemas/country"
          }
        },
        "required": [
          "city",
          "country",
          "line1",
          "postal_code",
          "region"
        ]
      },
      "additional_motor_vehicle_rental_data": {
        "type": "object",
        "nullable": true,
        "description": "Contains motor vehicle rental-specific fields for `Authorization` and `Transfer` requests. Optional for motor vehicle rental MCC transactions (MCC 3351–3500, 7512). Returns `null` for all other transactions.",
        "properties": {
          "motor_vehicle_rental_agreement_number": {
            "type": "string",
            "nullable": true,
            "description": "The rental agreement or contract reference number for the rental. Max 9 characters; longer values are truncated."
          },
          "customer_service_number": {
            "type": "string",
            "nullable": true,
            "description": "The phone number customers can call for support or inquiries related to their rental."
          },
          "extra_charge_details": {
            "type": "object",
            "nullable": true,
            "description": "Additional charges beyond the base rental rate being billed. Each field represents a specific charge type, in cents.",
            "properties": {
              "extra_mileage_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "fuel_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "insurance_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "late_return_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "one_way_service_fee_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "parking_violation_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              }
            }
          },
          "is_no_show": {
            "type": "boolean",
            "nullable": true,
            "default": false,
            "description": "An indicator that the cardholder is being billed for a reserved vehicle that was not actually rented (that is, a \"no-show\" charge)."
          },
          "number_of_days": {
            "type": "integer",
            "nullable": true,
            "description": "The total number of days for the vehicle rental."
          },
          "rental_rate": {
            "type": "string",
            "nullable": true,
            "description": "The daily rental rate for the vehicle, in cents."
          },
          "renter_name": {
            "type": "string",
            "nullable": true,
            "description": "The name of the person renting the vehicle."
          },
          "pickup_address": {
            "nullable": true,
            "description": "The full address of the rental pickup location.",
            "allOf": [
              {
                "$ref": "#/components/schemas/address"
              }
            ]
          },
          "pickup_date": {
            "type": "object",
            "nullable": true,
            "description": "The scheduled vehicle pickup date.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the pickup date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the pickup date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the pickup date."
              }
            }
          },
          "return_address": {
            "nullable": true,
            "description": "The full address of the vehicle return location.",
            "allOf": [
              {
                "$ref": "#/components/schemas/address"
              }
            ]
          },
          "return_date": {
            "type": "object",
            "nullable": true,
            "description": "The scheduled vehicle return date. Must be on or after `pickup_date`.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the return date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the return date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the return date."
              }
            }
          }
        }
      },
      "additional_buyer_charges": {
        "type": "object",
        "description": "Additional charges will be incurred by the buyer.\n\nThe following rules apply:\n\n- The `Merchant` must be enabled to charge these surcharges by setting the appropriate flags for each applicable surcharge to `true` using the PUT `/merchants` endpoint.\n- Only _one_ of the following charges can be applied during creation.\n",
        "nullable": true,
        "properties": {
          "convenience_amount": {
            "type": "integer",
            "description": "A convenience fee to charge the buyer for the transaction. This object property is mutually exclusive.",
            "nullable": true
          },
          "rent_surcharge_amount": {
            "type": "integer",
            "description": "A rent surcharge to charge the buyer for the transaction. This object property is mutually exclusive.",
            "nullable": true
          },
          "surcharge_amount": {
            "type": "integer",
            "description": "A surcharge amount to charge the buyer for the transaction. This object property is mutually exclusive.",
            "nullable": true
          }
        }
      },
      "additional_healthcare_data": {
        "type": "object",
        "nullable": true,
        "properties": {
          "clinic_amount": {
            "type": "integer",
            "description": "A clinic or other qualified medical amount for the transaction.",
            "nullable": true
          },
          "dental_amount": {
            "type": "integer",
            "description": "The dental amount for the transaction.",
            "nullable": true
          },
          "prescription_amount": {
            "type": "integer",
            "description": "The prescription/RX amount for the transaction.",
            "nullable": true
          },
          "vision_amount": {
            "type": "integer",
            "description": "The vision/optical amount for the transaction.",
            "nullable": true
          }
        }
      },
      "customer_reference_number": {
        "type": "string",
        "description": "A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records.",
        "maxLength": 17
      },
      "additional_purchase_data": {
        "type": "object",
        "description": "Additional information about the purchase used for [Level 2 and Level 3 Processing](/guides/online-payments/payment-features/level-2-level-3-processing). Please note that Visa is ending its Level 2 offering in April 2026.",
        "nullable": true,
        "properties": {
          "customer_reference_number": {
            "$ref": "#/components/schemas/customer_reference_number"
          },
          "customs_duty_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The duty in cents on the total purchase amount for the order."
          },
          "destination_country_code": {
            "type": "string",
            "nullable": true,
            "description": "The ISO country code of the order destination."
          },
          "destination_postal_code": {
            "type": "string",
            "nullable": true,
            "description": "The postal code of the order destination (10 characters).",
            "maxLength": 10
          },
          "discount_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The amount in cents of the discount for the order. You must include this field to qualify for Level 3 interchange benefits. Even if the value is (0), you should pass the field to qualify for Level 3."
          },
          "invoice_reference_number": {
            "type": "string",
            "nullable": true,
            "description": "The order's invoice number (max 15 characters).",
            "maxLength": 15
          },
          "order_date": {
            "type": "object",
            "nullable": true,
            "properties": {
              "day": {
                "type": "integer",
                "description": "Day of purchase (between 1 and 31)."
              },
              "month": {
                "type": "integer",
                "description": "Month of purchase (between 1 and 12)."
              },
              "year": {
                "type": "integer",
                "description": "Year of purchase (4-digit).",
                "minimum": 1990
              }
            }
          },
          "sales_tax": {
            "type": "integer",
            "nullable": true,
            "description": "- Total aggregate tax amount in cents for the entire purchase. Field is automatically calculated if you pass in the itemized tax amounts.\n- For non-taxable transactions either set `sales_tax` to 0 or omit from payload and also set `tax_exempt` to **True**.\n- Request must align so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`.\n- For Visa, this field no longer qualifies for lower interchange after April 17, 2026. Include `item_data` for Level 3 processing."
          },
          "sales_tax_finix_generated": {
            "type": "integer",
            "description": "The sales tax amount in cents Finix calculated from the `item_data` line items.",
            "nullable": true
          },
          "ship_from_postal_code": {
            "type": "string",
            "nullable": true,
            "description": "The postal code from where order is shipped (10 characters).",
            "maxLength": 10
          },
          "shipping_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The shipping cost in cents for the order.\n"
          },
          "tax_exempt": {
            "type": "boolean",
            "description": "- For tax exempt purchases set to **True**.\n- If set to **True**, request can't include `sales_tax`."
          },
          "item_data": {
            "type": "array",
            "description": "Additional information about the transaction. Used for Level 2 and Level 3 Processing.",
            "items": {
              "type": "object",
              "properties": {
                "amount_excluding_sales_tax": {
                  "type": "integer",
                  "description": "- Total cost of the line item in cents, excluding tax.\n- Must align with `sales_tax` so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`."
                },
                "amount_including_sales_tax": {
                  "type": "integer",
                  "description": "- Total cost of the line item in cents, including tax.\n- Must align with `sales_tax` so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`."
                },
                "commodity_code": {
                  "description": "A commodity code is a numeric code representing a particular product or service as defined by the National Institute of Governmental Purchasing. The code can be 3, 5, 7, or 11 digits in length. The longer the code the more granular the description of the product/service. (max 12 characters).",
                  "type": "string",
                  "maxLength": 12
                },
                "cost_per_unit": {
                  "type": "integer",
                  "description": "The price in cents, excluding tax, of one unit of the item purchased."
                },
                "item_description": {
                  "type": "string",
                  "description": "Required when `item_data` is supplied (max 25 characters).",
                  "maxLength": 25
                },
                "item_discount_amount": {
                  "type": "integer",
                  "description": "The item discount amount in cents. You must include this field to qualify for Level 3 interchange benefits. Even if the value is (0), you should pass the field to qualify for Level 3."
                },
                "merchant_product_code": {
                  "type": "string",
                  "description": "Merchant defined product code (max 12 characters).",
                  "maxLength": 12
                },
                "quantity": {
                  "type": "number",
                  "description": "The number of items purchased. Must be greater than 0.",
                  "minimum": 1,
                  "maximum": 99
                },
                "unit_of_measure": {
                  "type": "string",
                  "description": "The unit of measure of the purchased item (max 3 characters).",
                  "maxLength": 3
                },
                "sales_tax_amount": {
                  "type": "integer",
                  "description": "The sales tax amount in cents for the line item."
                },
                "sales_tax_rate": {
                  "type": "number",
                  "description": "The sales tax rate for the line item as a decimal (e.g., 0.25 equals 25%).",
                  "example": 0.25
                }
              }
            }
          }
        }
      },
      "amount": {
        "type": "integer",
        "description": "The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).",
        "example": 5000,
        "format": "int64"
      },
      "tags": {
        "type": "object",
        "title": "tags",
        "additionalProperties": true,
        "description": "Include up to 50 `key: value` pairs to annotate requests with custom metadata.\n- Maximum character length for individual `keys` is 40.\n- Maximum character length for individual `values` is 500.\n(For example, `order_number: 25`, `item_type: produce`, `department: sales`)",
        "nullable": true
      },
      "card_present_details": {
        "type": "object",
        "description": "Details needed to process card present transactions.",
        "nullable": true,
        "properties": {
          "approval_code": {
            "type": "string",
            "description": "Unique ID used to identify the approval of the `Transfer`.",
            "nullable": true
          },
          "brand": {
            "type": "string",
            "description": "The brand of the card saved in the `Payment Instrument`.",
            "nullable": true
          },
          "digital_signature_file_id": {
            "type": "string",
            "description": "If a signature was collected this will contain the the id of the `File` resource which stored the signature.",
            "nullable": true
          },
          "emv_data": {
            "type": "object",
            "description": "Encrypted card data used to process the transaction.",
            "nullable": true,
            "properties": {
              "application_identifier": {
                "type": "string",
                "description": "ID of the application used in the transaction. Tag 9F06 from the EMVCo standard."
              },
              "application_label": {
                "type": "string",
                "description": "EMV application label. Tag 50 from the EMVCo standard."
              },
              "application_preferred_name": {
                "type": "string",
                "description": "EMV application label with formatting (if provided). Tag 9F12 from the EMVCo standard.",
                "nullable": true
              },
              "application_transaction_counter": {
                "type": "string",
                "description": "Transaction number for the EMV application. Tag 9F36 from the EMVCo standard."
              },
              "cryptogram": {
                "type": "string",
                "description": "Cryptogram returned by the card. Tag 9F26 of the EMVCo standard."
              },
              "issuer_code_table_index": {
                "type": "string",
                "description": "The alphabet code table (according to ISO 8859) used by the EMV application (if provided). Tag 9F11.",
                "nullable": true
              },
              "pin_verified": {
                "type": "boolean",
                "description": "Whether the cardholder's PIN number was verified."
              },
              "tags": {
                "$ref": "#/components/schemas/tags"
              }
            }
          },
          "entry_mode": {
            "type": "string",
            "description": "Details of the card payment method used to process the transaction.\n\nThe possible enums are:\n\n- UNKNOWN - The method by which the payment card was used is unknown.\n- SWIPED - The card was swiped through a POS terminal.\n- CONTACTLESS - The payment was made by tapping a card on a POS terminal.\n- CHIP_ENTRY - The payment card was inserted into a card reader.\n",
            "enum": [
              "UNKNOWN",
              "SWIPED",
              "CONTACTLESS",
              "CHIP_ENTRY"
            ],
            "nullable": true
          },
          "masked_account_number": {
            "type": "string",
            "description": "Last four digits of the bank account number.",
            "nullable": true
          },
          "name": {
            "type": "string",
            "description": "The name of the card owner.",
            "nullable": true
          },
          "payment_type": {
            "type": "string",
            "description": "The type of `Payment Instrument` used in the transaction (or the original payment)."
          }
        }
      },
      "currency": {
        "type": "string",
        "description": "ISO 4217 3-letter currency code.",
        "enum": [
          "CAD",
          "USD"
        ]
      },
      "created_via_transfers_authorizations": {
        "type": "string",
        "description": "Gives more information about the product flow that was used to create the resource. Finix retains the right to add additional enums for this field without it being a breaking change.",
        "default": "UNKNOWN",
        "enum": [
          "CARD_PRESENT_ANDROID_APP",
          "CARD_PRESENT_ANDROID_APP_MANUAL_ENTRY",
          "CARD_PRESENT_ANDROID_D135_SDK",
          "CARD_PRESENT_DEVICE_READER_SDK",
          "CARD_PRESENT_IOS_APP",
          "CARD_PRESENT_IOS_APP_MANUAL_ENTRY",
          "CARD_PRESENT_IOS_D135_SDK",
          "CARD_PRESENT_IOS_TAP_TO_PAY",
          "CARD_PRESENT_IOS_TAP_TO_PAY_SDK",
          "CARD_PRESENT_SEMI_INTEGRATED_API",
          "CARD_PRESENT_STANDALONE",
          "CARD_PRESENT_STANDALONE_MANUAL_ENTRY",
          "CHECKOUT_FORM",
          "CYBERSOURCE",
          "DEVICE_ORDER",
          "PAYMENT_LINK",
          "PAYOUT_LINK",
          "PLUGIN_ADMOJI",
          "PLUGIN_CHECKOUT_CHAMP",
          "PLUGIN_FYNTEK",
          "PLUGIN_GAMBLE_ID",
          "PLUGIN_GAMMA_SWEEP",
          "PLUGIN_GR4VY",
          "PLUGIN_HYPERSWITCH",
          "PLUGIN_LACORE",
          "PLUGIN_PAYSIGHT",
          "PLUGIN_PRYZR",
          "PLUGIN_SERVMAN",
          "PLUGIN_SOAP_PAY",
          "PLUGIN_STICKYIO",
          "PLUGIN_TAGADA",
          "PLUGIN_WOO_COMMERCE",
          "PLUGIN_VRIO",
          "SUBSCRIPTION",
          "UNKNOWN",
          "VIRTUAL_TERMINAL"
        ]
      },
      "failure_code": {
        "type": "string",
        "description": "The code of the failure so the decline can be handled programmatically. For more info on how to handle the failure, see [Failure Codes](/additional-resources/developers/implementation-and-testing/failure-codes).",
        "nullable": true
      },
      "failure_message": {
        "type": "string",
        "description": "A human-readable description of why the transaction was declined. This will also include a suggestion on how to complete the payment.",
        "nullable": true
      },
      "idempotency_id": {
        "type": "string",
        "description": "Pass any randomly generated or internal ID to [idempotently](/api/section/idempotent-requests) identify `Transfers`, `Authorizations`, or refund requests.",
        "nullable": true
      },
      "ip_address_v4": {
        "type": "string",
        "description": "The card brands require the customer's IP address for online gaming clients. Only supports Internet Protocol version 4 (IPv4).",
        "example": "192.168.1.1",
        "nullable": true
      },
      "ip_address_details": {
        "type": "object",
        "nullable": true,
        "description": "This field returns `null` for all users except `ROLE_PLATFORM` users.",
        "properties": {
          "ipv4": {
            "type": "object",
            "properties": {
              "estimated_location": {
                "$ref": "#/components/schemas/address"
              },
              "ip": {
                "$ref": "#/components/schemas/ip_address_v4"
              },
              "latitude": {
                "type": "number",
                "description": "Geo-location based on the IP address."
              },
              "longitude": {
                "type": "number",
                "description": "Geo-location based on the IP address."
              }
            }
          }
        }
      },
      "raw": {
        "title": "Raw",
        "description": "Raw response from the processor.",
        "anyOf": [
          {
            "type": "object",
            "nullable": true
          },
          {
            "type": "string",
            "nullable": true
          }
        ]
      },
      "source": {
        "type": "string",
        "example": "PIxxxxxxxxxxxxxxxxxx",
        "description": "ID of the `Payment Instrument` where funds get debited."
      },
      "self": {
        "type": "object",
        "description": "Link to the resource that was used in the request.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "application_link": {
        "type": "object",
        "description": "Link to the `Application` the request was made under.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "merchant_identity": {
        "type": "object",
        "description": "Link to the `Identity` the `Merchant` was created under and the `Transfer` was submitted with.",
        "properties": {
          "href": {
            "type": "string"
          }
        }
      },
      "transfers": {
        "type": "object",
        "description": "Link to the `Transfer` the request was made under.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "authorization": {
        "type": "object",
        "title": "Authorization",
        "description": "A charge authorization",
        "properties": {
          "id": {
            "type": "string",
            "example": "AUxxxxxxxxxxxxxxxxxx",
            "description": "The ID of the `Authorization` resource."
          },
          "created_at": {
            "$ref": "#/components/schemas/created_at"
          },
          "updated_at": {
            "$ref": "#/components/schemas/updated_at"
          },
          "3d_secure_session": {
            "type": "string",
            "nullable": true,
            "description": "The ID of the `3D Secure Session` that authenticated the buyer. This field is `null` when the payment was not authenticated with a `3D Secure Session`.",
            "example": "3d_secure_session_f3fG3Zj8K958MTP5vpXAXX"
          },
          "3ds_redirect_url": {
            "type": "string",
            "description": "The redirect URL used for 3DS transactions (if supported by the processor).",
            "nullable": true
          },
          "additional_lodging_data": {
            "description": "Object detailing any additional lodging amounts included in the `Authorization`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/additional_lodging_data"
              }
            ]
          },
          "additional_motor_vehicle_rental_data": {
            "description": "Object detailing any additional motor vehicle rental amounts included in the `Authorization`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/additional_motor_vehicle_rental_data"
              }
            ]
          },
          "additional_buyer_charges": {
            "description": "Details about any [Buyer Charges](/guides/online-payments/payment-features/buyer-charges) included in the `Authorization`. The buyer charges are mutually exclusive.\n",
            "allOf": [
              {
                "$ref": "#/components/schemas/additional_buyer_charges"
              }
            ]
          },
          "additional_healthcare_data": {
            "description": "Object detailing any additional healthcare amounts included in the `Authorization`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/additional_healthcare_data"
              }
            ]
          },
          "additional_purchase_data": {
            "$ref": "#/components/schemas/additional_purchase_data"
          },
          "address_verification": {
            "type": "string",
            "description": "Details the results of the Address Verification checks.",
            "nullable": true
          },
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "amount_requested": {
            "type": "integer",
            "description": "When `default_partial_authorization_enabled` is set to **true**, `amount_requested` indicates the amount the cardholder attempted to authorize."
          },
          "application": {
            "type": "string",
            "description": "The ID of the `Application` resource the `Authorization` was created under."
          },
          "card_present_details": {
            "$ref": "#/components/schemas/card_present_details"
          },
          "credential_on_file": {
            "description": "An object that contains information about the credential on file authorization.\n",
            "type": "object",
            "nullable": true,
            "properties": {
              "initial_transfer_id": {
                "type": "string",
                "description": "The ID of the initial transfer in the series."
              },
              "type": {
                "type": "string",
                "enum": [
                  "RECURRING",
                  "UNSCHEDULED"
                ],
                "description": "The type of credential on file authorization."
              }
            }
          },
          "currency": {
            "$ref": "#/components/schemas/currency"
          },
          "created_via": {
            "$ref": "#/components/schemas/created_via_transfers_authorizations"
          },
          "device": {
            "type": "string",
            "example": "DVxxxxxxxxxxxxxxxxxx",
            "description": "The ID of the activated device.",
            "nullable": true
          },
          "expires_at": {
            "type": "string",
            "description": "`Authorization` expiration time.",
            "format": "date-time"
          },
          "failure_code": {
            "$ref": "#/components/schemas/failure_code"
          },
          "failure_message": {
            "$ref": "#/components/schemas/failure_message"
          },
          "identity": {
            "type": "string",
            "description": "ID of the buyer 'Identity' to run the card present authorization. Finix tokenizes the card associated with the provided 'Identity' and processes the authorization, removing the need to create a blank buyer `Identity`.",
            "default": null
          },
          "idempotency_id": {
            "$ref": "#/components/schemas/idempotency_id"
          },
          "ip_address_details": {
            "$ref": "#/components/schemas/ip_address_details"
          },
          "is_void": {
            "type": "boolean",
            "description": "Whether the `Authorization` has been voided."
          },
          "merchant": {
            "type": "string",
            "example": "MUxxxxxxxxxxxxxxxxxxxxxx",
            "description": "The ID of the `Merchant` resource the `Authorization` was created under."
          },
          "merchant_identity": {
            "type": "string",
            "example": "IDxxxxxxxxxxxxxxxxxxxxxx",
            "description": "The ID of the `Identity` resource used by the `Merchant` the `Authorization` was processed under."
          },
          "messages": {
            "type": "array",
            "description": "Message field that provides additional details. This field is typically **null**.",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "network_details": {
            "type": "object",
            "description": "Contains network-specific fields used by issuers to identify transactions.",
            "nullable": true,
            "properties": {
              "brand": {
                "type": "string",
                "description": "Card brand associated with the saved payment instrument.",
                "example": "VISA"
              },
              "authorization_code": {
                "type": "string",
                "description": "Code returned by the issuing bank when a transaction is authorized.",
                "example": 82533
              }
            }
          },
          "raw": {
            "$ref": "#/components/schemas/raw"
          },
          "receipt_last_printed_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the receipt was last printed.",
            "nullable": true
          },
          "security_code_verification": {
            "type": "string",
            "description": "Details the results of the Security Code Verification che",
            "nullable": true
          },
          "source": {
            "$ref": "#/components/schemas/source"
          },
          "state": {
            "type": "string",
            "enum": [
              "CANCELED",
              "PENDING",
              "FAILED",
              "SUCCEEDED",
              "UNKNOWN"
            ],
            "description": "The state of the `Authorization`."
          },
          "supplemental_fee": {
            "type": "integer",
            "format": "int64",
            "description": "Amount in cents for which an additional fee will be created in addition to any fees created from the assigned fee profile.",
            "nullable": true
          },
          "tags": {
            "$ref": "#/components/schemas/tags"
          },
          "trace_id": {
            "type": "string",
            "description": "Trace ID of the `Authorization`. The processor sends back the `trace_id` so you can track the authorization end-to-end."
          },
          "transfer": {
            "type": "string",
            "example": "TRxxxxxxxxxxxxxxxxxx",
            "description": "The ID of the `transfer` resource that gets created when the `Authorization` moves to **SUCCEEDED**.",
            "nullable": true
          },
          "void_state": {
            "type": "string",
            "description": "The state of the void attempt for the `Authorization`.",
            "enum": [
              "UNATTEMPTED",
              "PENDING",
              "SUCCEEDED"
            ]
          },
          "_links": {
            "type": "object",
            "properties": {
              "self": {
                "$ref": "#/components/schemas/self"
              },
              "application": {
                "$ref": "#/components/schemas/application_link"
              },
              "device": {
                "type": "object",
                "description": "Link to the `Device` the request was made under.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "merchant_identity": {
                "$ref": "#/components/schemas/merchant_identity"
              },
              "transfer": {
                "type": "object",
                "description": "Link to the `Transfer` created when the `Authorization` moves to **SUCCEEDED**.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "transfers": {
                "$ref": "#/components/schemas/transfers"
              }
            }
          }
        }
      }
    }
  }
}
```

## Create an Authorization with Level 3 processing

Send a POST /authorizations request and include the required fields for Level 3 processing.

### Level 3 Fields

Include the following `additional_purchase_data` fields:

| Field | API Field | Type | Description |
|  --- | --- | --- | --- |
| **Customer Reference Number** | `customer_reference_number` | *string*, **required** | A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records. (max `17` characters) |
| **Customs Duty Amount** | `customs_duty_amount` | *integer*, **required** | The costs related to import or export duties in cents. This field must have a value of at least `0`. |
| **Discount Amount** | `discount_amount` | *integer*, **required** | The amount in cents of the discount for the order. This field must have a value of at least `0`. |
| **Shipping Amount** | `shipping_amount` | *integer*, **required** | The costs related to shipping and handling in cents. This field must have a value of at least `0`. |
| **Tax Exempt** | `tax_exempt` | *boolean*, **optional** | For tax exempt purchases set to `true`. |


Include the following `item_data` fields for each line item:

| Field | API Field | Type | Description |
|  --- | --- | --- | --- |
| **Amount Excluding Sales Tax** | `amount_excluding_sales_tax` | *integer*, **required** | Total cost in cents of the line item excluding tax (must be greater than `0`). |
| **Amount Including Sales Tax** | `amount_including_sales_tax` | *integer*, **required** | Total cost in cents of the line item including tax (must be greater than `0`). |
| **Commodity Code** | `commodity_code` | *string*, **required** | A commodity code is a numeric code representing a particular product or service as defined by the National Institute of Governmental Purchasing. The code can be `3`, `5`, `7`, or `11` digits in length. The longer the code the more granular the description of the product/service. (max 12 characters) |
| **Cost per Item** | `cost_per_unit` | *integer*, **required** | The price in cents of one unit of the item purchased. |
| **Item Description** | `item_description` | *string*, **required** | A short, human-readable description of the line item (max `25` characters). |
| **Item Discount** | `item_discount_amount` | *integer*, **required** | The discount amount in cents applied to this individual line item. For an order-level discount, use `discount_amount`. |
| **Merchant Product Code** | `merchant_product_code` | *string*, **required** | Merchant defined product code (max `12` characters). |
| **Quantity** | `quantity` | *integer*, **required** | The number of items purchased. Must be greater than `0`. |
| **Unit of Measure** | `unit_of_measure` | *string*, **required** | The unit of measure of the purchased item (max `3` characters). |


### Request

```shell
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 '{
    "additional_purchase_data": {
      "customer_reference_number": "PO-2024-3842",
      "customs_duty_amount": 0,
      "discount_amount": 100,
      "item_data": [
        {
          "amount_excluding_sales_tax": 400,
          "amount_including_sales_tax": 440,
          "commodity_code": "175-62-20",
          "cost_per_unit": 500,
          "item_description": "IT Network Assessment",
          "item_discount_amount": 100,
          "merchant_product_code": "SVC-NET-ASMT",
          "quantity": 1,
          "unit_of_measure": "HUR"
        },
        {
          "amount_excluding_sales_tax": 500,
          "amount_including_sales_tax": 550,
          "commodity_code": "207-72-54",
          "cost_per_unit": 500,
          "item_description": "USB-C Charging Cable 6ft",
          "item_discount_amount": 0,
          "merchant_product_code": "CBL-USBC-6FT",
          "quantity": 1,
          "unit_of_measure": "EA"
        }
      ],
      "shipping_amount": 100
    },
    "amount": 990,
    "currency": "USD",
    "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
    "source": "PIkxmtueemLD6dN9ZoWGHT44"
  }'
```

### Response

A successful request returns a `201 Created` status code and includes an Authorization resource with Level 3 processing details:

Example
Authorization - Level 3 Processing
```json Authorization - Level 3 Processing
{
  "id": "AUzck2De5WUgJY1kCUkwLtT",
  "created_at": "2026-10-27T20:24:47.60Z",
  "updated_at": "2026-10-27T20:24:47.60Z",
  "3d_secure_session": null,
  "3ds_redirect_url": null,
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_lodging_data": null,
  "additional_motor_vehicle_rental_data": null,
  "additional_purchase_data": { // [!code highlight]
    "customer_reference_number": "PO-2024-3842", // [!code highlight]
    "customs_duty_amount": 0, // [!code highlight]
    "destination_country_code": null, // [!code highlight]
    "destination_postal_code": null, // [!code highlight]
    "discount_amount": 100, // [!code highlight]
    "invoice_reference_number": null, // [!code highlight]
    "order_date": null, // [!code highlight]
    "sales_tax": null, // [!code highlight]
    "sales_tax_finix_generated": 90, // [!code highlight]
    "ship_from_postal_code": null, // [!code highlight]
    "shipping_amount": 100, // [!code highlight]
    "tax_exempt": false, // [!code highlight]
    "item_data": [ // [!code highlight]
      { // [!code highlight]
        "cost_per_unit": 500, // [!code highlight]
        "item_description": "IT Network Assessment", // [!code highlight]
        "item_discount_amount": 100, // [!code highlight]
        "merchant_product_code": "SVC-NET-ASMT", // [!code highlight]
        "quantity": 1, // [!code highlight]
        "amount_excluding_sales_tax": 400, // [!code highlight]
        "amount_including_sales_tax": 440, // [!code highlight]
        "unit_of_measure": "HUR", // [!code highlight]
        "commodity_code": "175-62-20", // [!code highlight]
        "sales_tax_amount": 40, // [!code highlight]
        "sales_tax_rate": 0.1 // [!code highlight]
      }, // [!code highlight]
      { // [!code highlight]
        "cost_per_unit": 500, // [!code highlight]
        "item_description": "USB-C Charging Cable 6ft", // [!code highlight]
        "item_discount_amount": 0, // [!code highlight]
        "merchant_product_code": "CBL-USBC-6FT", // [!code highlight]
        "quantity": 1, // [!code highlight]
        "amount_excluding_sales_tax": 500, // [!code highlight]
        "amount_including_sales_tax": 550, // [!code highlight]
        "unit_of_measure": "EA", // [!code highlight]
        "commodity_code": "207-72-54", // [!code highlight]
        "sales_tax_amount": 50, // [!code highlight]
        "sales_tax_rate": 0.1 // [!code highlight]
      } // [!code highlight]
    ] // [!code highlight]
  }, // [!code highlight]
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "amount": 990,
  "amount_requested": 990,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_via": "UNKNOWN",
  "currency": "USD",
  "expires_at": "2026-11-06T20:24:47.60Z",
  "failure_code": null,
  "failure_message": null,
  "idempotency_id": null,
  "ip_address_details": null,
  "is_void": false,
  "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
  "merchant_identity": "IDjvxGeXBLKH1V9YnWm1CS4n",
  "messages": [],
  "network_details": {
    "brand": "VISA",
    "authorization_code": "517554"
  },
  "raw": null,
  "receipt_last_printed_at": null,
  "security_code_verification": "MATCHED",
  "source": "PIkxmtueemLD6dN9ZoWGHT44",
  "state": "SUCCEEDED",
  "supplemental_fee": null,
  "tags": {},
  "trace_id": "9670df3e-bbe6-4def-a2a4-a59b99e056a7",
  "transfer": null,
  "void_state": "UNATTEMPTED",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/authorizations/AUzck2De5WUgJY1kCUkwLtT"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n"
    }
  }
}
```

API Definition
```json
{
  "$ref": "#/components/schemas/authorization",
  "components": {
    "schemas": {
      "created_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was created."
      },
      "updated_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was last updated."
      },
      "additional_lodging_data": {
        "type": "object",
        "nullable": true,
        "description": "Contains lodging-specific fields for `Authorization` and `Transfer` requests. Optional for lodging MCC transactions (MCC 3501–3999, 7011). Returns `null` for all other transactions.",
        "properties": {
          "check_in_date": {
            "type": "object",
            "nullable": true,
            "description": "The guest's scheduled arrival date.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the check-in date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the check-in date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the check-in date."
              }
            }
          },
          "check_out_date": {
            "type": "object",
            "nullable": true,
            "description": "The guest's scheduled departure date. Must represent a date on or after `check_in_date`.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the check-out date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the check-out date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the check-out date."
              }
            }
          },
          "customer_service_phone": {
            "type": "string",
            "nullable": true,
            "description": "The phone number guests can call for support or inquiries related to their stay."
          },
          "extra_charge_details": {
            "type": "object",
            "nullable": true,
            "description": "Additional charges billed beyond the room rate. Each field represents a specific charge type, in cents.",
            "properties": {
              "restaurant_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "mini_bar_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "laundry_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "other_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "phone_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "gift_shop_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              }
            }
          },
          "hotel_agreement_number": {
            "type": "string",
            "nullable": true,
            "description": "The folio or agreement number associated with the reservation. Max 12 characters; longer values are truncated."
          },
          "is_advance_deposit": {
            "type": "boolean",
            "nullable": true,
            "default": false,
            "description": "Indicates whether the lodging charge is an advance deposit."
          },
          "is_no_show": {
            "type": "boolean",
            "nullable": true,
            "default": false,
            "description": "Set to `true` if the cardholder is being billed for a reserved room that was not occupied."
          },
          "number_of_nights": {
            "type": "integer",
            "nullable": true,
            "description": "The total number of nights for the lodging stay."
          },
          "property_phone": {
            "type": "string",
            "nullable": true,
            "description": "The direct phone number of the lodging property."
          },
          "room_rate": {
            "type": "string",
            "nullable": true,
            "description": "The nightly room rate, in cents."
          },
          "room_tax": {
            "type": "string",
            "nullable": true,
            "description": "The tax amount applied to the room rate, in cents."
          }
        }
      },
      "country": {
        "type": "string",
        "enum": [
          "ABW",
          "AFG",
          "AGO",
          "AIA",
          "ALA",
          "ALB",
          "AND",
          "ARE",
          "ARG",
          "ARM",
          "ASM",
          "ATA",
          "ATF",
          "ATG",
          "AUS",
          "AUT",
          "AZE",
          "BDI",
          "BEL",
          "BEN",
          "BES",
          "BFA",
          "BGD",
          "BGR",
          "BHR",
          "BHS",
          "BIH",
          "BLM",
          "BLR",
          "BLZ",
          "BMU",
          "BOL",
          "BRA",
          "BRB",
          "BRN",
          "BTN",
          "BVT",
          "BWA",
          "CAF",
          "CAN",
          "CCK",
          "CHE",
          "CHL",
          "CHN",
          "CIV",
          "CMR",
          "COD",
          "COG",
          "COK",
          "COL",
          "COM",
          "CPV",
          "CRI",
          "CUB",
          "CUW",
          "CXR",
          "CYM",
          "CYP",
          "CZE",
          "DEU",
          "DJI",
          "DMA",
          "DNK",
          "DOM",
          "DZA",
          "ECU",
          "EGY",
          "ERI",
          "ESH",
          "ESP",
          "EST",
          "ETH",
          "FIN",
          "FJI",
          "FLK",
          "FRA",
          "FRO",
          "FSM",
          "GAB",
          "GBR",
          "GEO",
          "GGY",
          "GHA",
          "GIB",
          "GIN",
          "GLP",
          "GMB",
          "GNB",
          "GNQ",
          "GRC",
          "GRD",
          "GRL",
          "GTM",
          "GUF",
          "GUM",
          "GUY",
          "HKG",
          "HMD",
          "HND",
          "HRV",
          "HTI",
          "HUN",
          "IDN",
          "IMN",
          "IND",
          "IOT",
          "IRL",
          "IRN",
          "IRQ",
          "ISL",
          "ISR",
          "ITA",
          "JAM",
          "JEY",
          "JOR",
          "JPN",
          "KAZ",
          "KEN",
          "KGZ",
          "KHM",
          "KIR",
          "KNA",
          "KOR",
          "KWT",
          "LAO",
          "LBN",
          "LBR",
          "LBY",
          "LCA",
          "LIE",
          "LKA",
          "LSO",
          "LTU",
          "LUX",
          "LVA",
          "MAC",
          "MAF",
          "MAR",
          "MCO",
          "MDA",
          "MDG",
          "MDV",
          "MEX",
          "MHL",
          "MKD",
          "MLI",
          "MLT",
          "MMR",
          "MNE",
          "MNG",
          "MNP",
          "MRT",
          "MSR",
          "MTQ",
          "MUS",
          "MWI",
          "MYS",
          "MYT",
          "NAM",
          "NCL",
          "NER",
          "NFK",
          "NGA",
          "NIC",
          "NIU",
          "NLD",
          "NOR",
          "NPL",
          "NRU",
          "NZL",
          "OMN",
          "PAK",
          "PAN",
          "PCN",
          "PER",
          "PHL",
          "PLW",
          "PNG",
          "POL",
          "PRI",
          "PRK",
          "PRT",
          "PRY",
          "PSE",
          "PYF",
          "QAT",
          "REU",
          "ROU",
          "RUS",
          "RWA",
          "SAU",
          "SDN",
          "SEN",
          "SGP",
          "SGS",
          "SHN",
          "SJM",
          "SLB",
          "SLE",
          "SLV",
          "SMR",
          "SOM",
          "SPM",
          "SRB",
          "SSD",
          "STP",
          "SUR",
          "SVK",
          "SVN",
          "SWE",
          "SWZ",
          "SXM",
          "SYC",
          "SYR",
          "TCA",
          "TCD",
          "TGO",
          "THA",
          "TJK",
          "TKL",
          "TKM",
          "TLS",
          "TON",
          "TTO",
          "TUN",
          "TUR",
          "TUV",
          "TWN",
          "TZA",
          "UGA",
          "UKR",
          "UMI",
          "URY",
          "USA",
          "UZB",
          "VAT",
          "VCT",
          "VEN",
          "VGB",
          "VIR",
          "VNM",
          "VUT",
          "WLF",
          "WSM",
          "XKX",
          "YEM",
          "ZAF",
          "ZMB",
          "ZWE"
        ],
        "nullable": true
      },
      "address": {
        "type": "object",
        "properties": {
          "line1": {
            "type": "string",
            "minLength": 1,
            "description": "First line of the address (max 35 characters).",
            "nullable": true
          },
          "line2": {
            "type": "string",
            "minLength": 1,
            "description": "Second line of the address (max 35 characters).",
            "nullable": true
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "description": "City (max 20 characters).",
            "nullable": true
          },
          "region": {
            "type": "string",
            "minLength": 1,
            "description": "2-letter State code.",
            "nullable": true
          },
          "postal_code": {
            "type": "string",
            "minLength": 1,
            "description": "Zip or Postal code (max 7 characters).",
            "nullable": true
          },
          "country": {
            "$ref": "#/components/schemas/country"
          }
        },
        "required": [
          "city",
          "country",
          "line1",
          "postal_code",
          "region"
        ]
      },
      "additional_motor_vehicle_rental_data": {
        "type": "object",
        "nullable": true,
        "description": "Contains motor vehicle rental-specific fields for `Authorization` and `Transfer` requests. Optional for motor vehicle rental MCC transactions (MCC 3351–3500, 7512). Returns `null` for all other transactions.",
        "properties": {
          "motor_vehicle_rental_agreement_number": {
            "type": "string",
            "nullable": true,
            "description": "The rental agreement or contract reference number for the rental. Max 9 characters; longer values are truncated."
          },
          "customer_service_number": {
            "type": "string",
            "nullable": true,
            "description": "The phone number customers can call for support or inquiries related to their rental."
          },
          "extra_charge_details": {
            "type": "object",
            "nullable": true,
            "description": "Additional charges beyond the base rental rate being billed. Each field represents a specific charge type, in cents.",
            "properties": {
              "extra_mileage_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "fuel_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "insurance_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "late_return_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "one_way_service_fee_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              },
              "parking_violation_amount": {
                "type": "integer",
                "nullable": true,
                "description": "The amount of the additional charge, in cents."
              }
            }
          },
          "is_no_show": {
            "type": "boolean",
            "nullable": true,
            "default": false,
            "description": "An indicator that the cardholder is being billed for a reserved vehicle that was not actually rented (that is, a \"no-show\" charge)."
          },
          "number_of_days": {
            "type": "integer",
            "nullable": true,
            "description": "The total number of days for the vehicle rental."
          },
          "rental_rate": {
            "type": "string",
            "nullable": true,
            "description": "The daily rental rate for the vehicle, in cents."
          },
          "renter_name": {
            "type": "string",
            "nullable": true,
            "description": "The name of the person renting the vehicle."
          },
          "pickup_address": {
            "nullable": true,
            "description": "The full address of the rental pickup location.",
            "allOf": [
              {
                "$ref": "#/components/schemas/address"
              }
            ]
          },
          "pickup_date": {
            "type": "object",
            "nullable": true,
            "description": "The scheduled vehicle pickup date.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the pickup date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the pickup date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the pickup date."
              }
            }
          },
          "return_address": {
            "nullable": true,
            "description": "The full address of the vehicle return location.",
            "allOf": [
              {
                "$ref": "#/components/schemas/address"
              }
            ]
          },
          "return_date": {
            "type": "object",
            "nullable": true,
            "description": "The scheduled vehicle return date. Must be on or after `pickup_date`.",
            "properties": {
              "month": {
                "type": "integer",
                "description": "The month of the return date."
              },
              "day": {
                "type": "integer",
                "description": "The day of the return date."
              },
              "year": {
                "type": "integer",
                "description": "The year of the return date."
              }
            }
          }
        }
      },
      "additional_buyer_charges": {
        "type": "object",
        "description": "Additional charges will be incurred by the buyer.\n\nThe following rules apply:\n\n- The `Merchant` must be enabled to charge these surcharges by setting the appropriate flags for each applicable surcharge to `true` using the PUT `/merchants` endpoint.\n- Only _one_ of the following charges can be applied during creation.\n",
        "nullable": true,
        "properties": {
          "convenience_amount": {
            "type": "integer",
            "description": "A convenience fee to charge the buyer for the transaction. This object property is mutually exclusive.",
            "nullable": true
          },
          "rent_surcharge_amount": {
            "type": "integer",
            "description": "A rent surcharge to charge the buyer for the transaction. This object property is mutually exclusive.",
            "nullable": true
          },
          "surcharge_amount": {
            "type": "integer",
            "description": "A surcharge amount to charge the buyer for the transaction. This object property is mutually exclusive.",
            "nullable": true
          }
        }
      },
      "additional_healthcare_data": {
        "type": "object",
        "nullable": true,
        "properties": {
          "clinic_amount": {
            "type": "integer",
            "description": "A clinic or other qualified medical amount for the transaction.",
            "nullable": true
          },
          "dental_amount": {
            "type": "integer",
            "description": "The dental amount for the transaction.",
            "nullable": true
          },
          "prescription_amount": {
            "type": "integer",
            "description": "The prescription/RX amount for the transaction.",
            "nullable": true
          },
          "vision_amount": {
            "type": "integer",
            "description": "The vision/optical amount for the transaction.",
            "nullable": true
          }
        }
      },
      "customer_reference_number": {
        "type": "string",
        "description": "A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records.",
        "maxLength": 17
      },
      "additional_purchase_data": {
        "type": "object",
        "description": "Additional information about the purchase used for [Level 2 and Level 3 Processing](/guides/online-payments/payment-features/level-2-level-3-processing). Please note that Visa is ending its Level 2 offering in April 2026.",
        "nullable": true,
        "properties": {
          "customer_reference_number": {
            "$ref": "#/components/schemas/customer_reference_number"
          },
          "customs_duty_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The duty in cents on the total purchase amount for the order."
          },
          "destination_country_code": {
            "type": "string",
            "nullable": true,
            "description": "The ISO country code of the order destination."
          },
          "destination_postal_code": {
            "type": "string",
            "nullable": true,
            "description": "The postal code of the order destination (10 characters).",
            "maxLength": 10
          },
          "discount_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The amount in cents of the discount for the order. You must include this field to qualify for Level 3 interchange benefits. Even if the value is (0), you should pass the field to qualify for Level 3."
          },
          "invoice_reference_number": {
            "type": "string",
            "nullable": true,
            "description": "The order's invoice number (max 15 characters).",
            "maxLength": 15
          },
          "order_date": {
            "type": "object",
            "nullable": true,
            "properties": {
              "day": {
                "type": "integer",
                "description": "Day of purchase (between 1 and 31)."
              },
              "month": {
                "type": "integer",
                "description": "Month of purchase (between 1 and 12)."
              },
              "year": {
                "type": "integer",
                "description": "Year of purchase (4-digit).",
                "minimum": 1990
              }
            }
          },
          "sales_tax": {
            "type": "integer",
            "nullable": true,
            "description": "- Total aggregate tax amount in cents for the entire purchase. Field is automatically calculated if you pass in the itemized tax amounts.\n- For non-taxable transactions either set `sales_tax` to 0 or omit from payload and also set `tax_exempt` to **True**.\n- Request must align so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`.\n- For Visa, this field no longer qualifies for lower interchange after April 17, 2026. Include `item_data` for Level 3 processing."
          },
          "sales_tax_finix_generated": {
            "type": "integer",
            "description": "The sales tax amount in cents Finix calculated from the `item_data` line items.",
            "nullable": true
          },
          "ship_from_postal_code": {
            "type": "string",
            "nullable": true,
            "description": "The postal code from where order is shipped (10 characters).",
            "maxLength": 10
          },
          "shipping_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The shipping cost in cents for the order.\n"
          },
          "tax_exempt": {
            "type": "boolean",
            "description": "- For tax exempt purchases set to **True**.\n- If set to **True**, request can't include `sales_tax`."
          },
          "item_data": {
            "type": "array",
            "description": "Additional information about the transaction. Used for Level 2 and Level 3 Processing.",
            "items": {
              "type": "object",
              "properties": {
                "amount_excluding_sales_tax": {
                  "type": "integer",
                  "description": "- Total cost of the line item in cents, excluding tax.\n- Must align with `sales_tax` so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`."
                },
                "amount_including_sales_tax": {
                  "type": "integer",
                  "description": "- Total cost of the line item in cents, including tax.\n- Must align with `sales_tax` so `amount_excluding_sales_tax` + `sales_tax` = `amount_including_sales_tax`."
                },
                "commodity_code": {
                  "description": "A commodity code is a numeric code representing a particular product or service as defined by the National Institute of Governmental Purchasing. The code can be 3, 5, 7, or 11 digits in length. The longer the code the more granular the description of the product/service. (max 12 characters).",
                  "type": "string",
                  "maxLength": 12
                },
                "cost_per_unit": {
                  "type": "integer",
                  "description": "The price in cents, excluding tax, of one unit of the item purchased."
                },
                "item_description": {
                  "type": "string",
                  "description": "Required when `item_data` is supplied (max 25 characters).",
                  "maxLength": 25
                },
                "item_discount_amount": {
                  "type": "integer",
                  "description": "The item discount amount in cents. You must include this field to qualify for Level 3 interchange benefits. Even if the value is (0), you should pass the field to qualify for Level 3."
                },
                "merchant_product_code": {
                  "type": "string",
                  "description": "Merchant defined product code (max 12 characters).",
                  "maxLength": 12
                },
                "quantity": {
                  "type": "number",
                  "description": "The number of items purchased. Must be greater than 0.",
                  "minimum": 1,
                  "maximum": 99
                },
                "unit_of_measure": {
                  "type": "string",
                  "description": "The unit of measure of the purchased item (max 3 characters).",
                  "maxLength": 3
                },
                "sales_tax_amount": {
                  "type": "integer",
                  "description": "The sales tax amount in cents for the line item."
                },
                "sales_tax_rate": {
                  "type": "number",
                  "description": "The sales tax rate for the line item as a decimal (e.g., 0.25 equals 25%).",
                  "example": 0.25
                }
              }
            }
          }
        }
      },
      "amount": {
        "type": "integer",
        "description": "The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).",
        "example": 5000,
        "format": "int64"
      },
      "tags": {
        "type": "object",
        "title": "tags",
        "additionalProperties": true,
        "description": "Include up to 50 `key: value` pairs to annotate requests with custom metadata.\n- Maximum character length for individual `keys` is 40.\n- Maximum character length for individual `values` is 500.\n(For example, `order_number: 25`, `item_type: produce`, `department: sales`)",
        "nullable": true
      },
      "card_present_details": {
        "type": "object",
        "description": "Details needed to process card present transactions.",
        "nullable": true,
        "properties": {
          "approval_code": {
            "type": "string",
            "description": "Unique ID used to identify the approval of the `Transfer`.",
            "nullable": true
          },
          "brand": {
            "type": "string",
            "description": "The brand of the card saved in the `Payment Instrument`.",
            "nullable": true
          },
          "digital_signature_file_id": {
            "type": "string",
            "description": "If a signature was collected this will contain the the id of the `File` resource which stored the signature.",
            "nullable": true
          },
          "emv_data": {
            "type": "object",
            "description": "Encrypted card data used to process the transaction.",
            "nullable": true,
            "properties": {
              "application_identifier": {
                "type": "string",
                "description": "ID of the application used in the transaction. Tag 9F06 from the EMVCo standard."
              },
              "application_label": {
                "type": "string",
                "description": "EMV application label. Tag 50 from the EMVCo standard."
              },
              "application_preferred_name": {
                "type": "string",
                "description": "EMV application label with formatting (if provided). Tag 9F12 from the EMVCo standard.",
                "nullable": true
              },
              "application_transaction_counter": {
                "type": "string",
                "description": "Transaction number for the EMV application. Tag 9F36 from the EMVCo standard."
              },
              "cryptogram": {
                "type": "string",
                "description": "Cryptogram returned by the card. Tag 9F26 of the EMVCo standard."
              },
              "issuer_code_table_index": {
                "type": "string",
                "description": "The alphabet code table (according to ISO 8859) used by the EMV application (if provided). Tag 9F11.",
                "nullable": true
              },
              "pin_verified": {
                "type": "boolean",
                "description": "Whether the cardholder's PIN number was verified."
              },
              "tags": {
                "$ref": "#/components/schemas/tags"
              }
            }
          },
          "entry_mode": {
            "type": "string",
            "description": "Details of the card payment method used to process the transaction.\n\nThe possible enums are:\n\n- UNKNOWN - The method by which the payment card was used is unknown.\n- SWIPED - The card was swiped through a POS terminal.\n- CONTACTLESS - The payment was made by tapping a card on a POS terminal.\n- CHIP_ENTRY - The payment card was inserted into a card reader.\n",
            "enum": [
              "UNKNOWN",
              "SWIPED",
              "CONTACTLESS",
              "CHIP_ENTRY"
            ],
            "nullable": true
          },
          "masked_account_number": {
            "type": "string",
            "description": "Last four digits of the bank account number.",
            "nullable": true
          },
          "name": {
            "type": "string",
            "description": "The name of the card owner.",
            "nullable": true
          },
          "payment_type": {
            "type": "string",
            "description": "The type of `Payment Instrument` used in the transaction (or the original payment)."
          }
        }
      },
      "currency": {
        "type": "string",
        "description": "ISO 4217 3-letter currency code.",
        "enum": [
          "CAD",
          "USD"
        ]
      },
      "created_via_transfers_authorizations": {
        "type": "string",
        "description": "Gives more information about the product flow that was used to create the resource. Finix retains the right to add additional enums for this field without it being a breaking change.",
        "default": "UNKNOWN",
        "enum": [
          "CARD_PRESENT_ANDROID_APP",
          "CARD_PRESENT_ANDROID_APP_MANUAL_ENTRY",
          "CARD_PRESENT_ANDROID_D135_SDK",
          "CARD_PRESENT_DEVICE_READER_SDK",
          "CARD_PRESENT_IOS_APP",
          "CARD_PRESENT_IOS_APP_MANUAL_ENTRY",
          "CARD_PRESENT_IOS_D135_SDK",
          "CARD_PRESENT_IOS_TAP_TO_PAY",
          "CARD_PRESENT_IOS_TAP_TO_PAY_SDK",
          "CARD_PRESENT_SEMI_INTEGRATED_API",
          "CARD_PRESENT_STANDALONE",
          "CARD_PRESENT_STANDALONE_MANUAL_ENTRY",
          "CHECKOUT_FORM",
          "CYBERSOURCE",
          "DEVICE_ORDER",
          "PAYMENT_LINK",
          "PAYOUT_LINK",
          "PLUGIN_ADMOJI",
          "PLUGIN_CHECKOUT_CHAMP",
          "PLUGIN_FYNTEK",
          "PLUGIN_GAMBLE_ID",
          "PLUGIN_GAMMA_SWEEP",
          "PLUGIN_GR4VY",
          "PLUGIN_HYPERSWITCH",
          "PLUGIN_LACORE",
          "PLUGIN_PAYSIGHT",
          "PLUGIN_PRYZR",
          "PLUGIN_SERVMAN",
          "PLUGIN_SOAP_PAY",
          "PLUGIN_STICKYIO",
          "PLUGIN_TAGADA",
          "PLUGIN_WOO_COMMERCE",
          "PLUGIN_VRIO",
          "SUBSCRIPTION",
          "UNKNOWN",
          "VIRTUAL_TERMINAL"
        ]
      },
      "failure_code": {
        "type": "string",
        "description": "The code of the failure so the decline can be handled programmatically. For more info on how to handle the failure, see [Failure Codes](/additional-resources/developers/implementation-and-testing/failure-codes).",
        "nullable": true
      },
      "failure_message": {
        "type": "string",
        "description": "A human-readable description of why the transaction was declined. This will also include a suggestion on how to complete the payment.",
        "nullable": true
      },
      "idempotency_id": {
        "type": "string",
        "description": "Pass any randomly generated or internal ID to [idempotently](/api/section/idempotent-requests) identify `Transfers`, `Authorizations`, or refund requests.",
        "nullable": true
      },
      "ip_address_v4": {
        "type": "string",
        "description": "The card brands require the customer's IP address for online gaming clients. Only supports Internet Protocol version 4 (IPv4).",
        "example": "192.168.1.1",
        "nullable": true
      },
      "ip_address_details": {
        "type": "object",
        "nullable": true,
        "description": "This field returns `null` for all users except `ROLE_PLATFORM` users.",
        "properties": {
          "ipv4": {
            "type": "object",
            "properties": {
              "estimated_location": {
                "$ref": "#/components/schemas/address"
              },
              "ip": {
                "$ref": "#/components/schemas/ip_address_v4"
              },
              "latitude": {
                "type": "number",
                "description": "Geo-location based on the IP address."
              },
              "longitude": {
                "type": "number",
                "description": "Geo-location based on the IP address."
              }
            }
          }
        }
      },
      "raw": {
        "title": "Raw",
        "description": "Raw response from the processor.",
        "anyOf": [
          {
            "type": "object",
            "nullable": true
          },
          {
            "type": "string",
            "nullable": true
          }
        ]
      },
      "source": {
        "type": "string",
        "example": "PIxxxxxxxxxxxxxxxxxx",
        "description": "ID of the `Payment Instrument` where funds get debited."
      },
      "self": {
        "type": "object",
        "description": "Link to the resource that was used in the request.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "application_link": {
        "type": "object",
        "description": "Link to the `Application` the request was made under.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "merchant_identity": {
        "type": "object",
        "description": "Link to the `Identity` the `Merchant` was created under and the `Transfer` was submitted with.",
        "properties": {
          "href": {
            "type": "string"
          }
        }
      },
      "transfers": {
        "type": "object",
        "description": "Link to the `Transfer` the request was made under.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "authorization": {
        "type": "object",
        "title": "Authorization",
        "description": "A charge authorization",
        "properties": {
          "id": {
            "type": "string",
            "example": "AUxxxxxxxxxxxxxxxxxx",
            "description": "The ID of the `Authorization` resource."
          },
          "created_at": {
            "$ref": "#/components/schemas/created_at"
          },
          "updated_at": {
            "$ref": "#/components/schemas/updated_at"
          },
          "3d_secure_session": {
            "type": "string",
            "nullable": true,
            "description": "The ID of the `3D Secure Session` that authenticated the buyer. This field is `null` when the payment was not authenticated with a `3D Secure Session`.",
            "example": "3d_secure_session_f3fG3Zj8K958MTP5vpXAXX"
          },
          "3ds_redirect_url": {
            "type": "string",
            "description": "The redirect URL used for 3DS transactions (if supported by the processor).",
            "nullable": true
          },
          "additional_lodging_data": {
            "description": "Object detailing any additional lodging amounts included in the `Authorization`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/additional_lodging_data"
              }
            ]
          },
          "additional_motor_vehicle_rental_data": {
            "description": "Object detailing any additional motor vehicle rental amounts included in the `Authorization`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/additional_motor_vehicle_rental_data"
              }
            ]
          },
          "additional_buyer_charges": {
            "description": "Details about any [Buyer Charges](/guides/online-payments/payment-features/buyer-charges) included in the `Authorization`. The buyer charges are mutually exclusive.\n",
            "allOf": [
              {
                "$ref": "#/components/schemas/additional_buyer_charges"
              }
            ]
          },
          "additional_healthcare_data": {
            "description": "Object detailing any additional healthcare amounts included in the `Authorization`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/additional_healthcare_data"
              }
            ]
          },
          "additional_purchase_data": {
            "$ref": "#/components/schemas/additional_purchase_data"
          },
          "address_verification": {
            "type": "string",
            "description": "Details the results of the Address Verification checks.",
            "nullable": true
          },
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "amount_requested": {
            "type": "integer",
            "description": "When `default_partial_authorization_enabled` is set to **true**, `amount_requested` indicates the amount the cardholder attempted to authorize."
          },
          "application": {
            "type": "string",
            "description": "The ID of the `Application` resource the `Authorization` was created under."
          },
          "card_present_details": {
            "$ref": "#/components/schemas/card_present_details"
          },
          "credential_on_file": {
            "description": "An object that contains information about the credential on file authorization.\n",
            "type": "object",
            "nullable": true,
            "properties": {
              "initial_transfer_id": {
                "type": "string",
                "description": "The ID of the initial transfer in the series."
              },
              "type": {
                "type": "string",
                "enum": [
                  "RECURRING",
                  "UNSCHEDULED"
                ],
                "description": "The type of credential on file authorization."
              }
            }
          },
          "currency": {
            "$ref": "#/components/schemas/currency"
          },
          "created_via": {
            "$ref": "#/components/schemas/created_via_transfers_authorizations"
          },
          "device": {
            "type": "string",
            "example": "DVxxxxxxxxxxxxxxxxxx",
            "description": "The ID of the activated device.",
            "nullable": true
          },
          "expires_at": {
            "type": "string",
            "description": "`Authorization` expiration time.",
            "format": "date-time"
          },
          "failure_code": {
            "$ref": "#/components/schemas/failure_code"
          },
          "failure_message": {
            "$ref": "#/components/schemas/failure_message"
          },
          "identity": {
            "type": "string",
            "description": "ID of the buyer 'Identity' to run the card present authorization. Finix tokenizes the card associated with the provided 'Identity' and processes the authorization, removing the need to create a blank buyer `Identity`.",
            "default": null
          },
          "idempotency_id": {
            "$ref": "#/components/schemas/idempotency_id"
          },
          "ip_address_details": {
            "$ref": "#/components/schemas/ip_address_details"
          },
          "is_void": {
            "type": "boolean",
            "description": "Whether the `Authorization` has been voided."
          },
          "merchant": {
            "type": "string",
            "example": "MUxxxxxxxxxxxxxxxxxxxxxx",
            "description": "The ID of the `Merchant` resource the `Authorization` was created under."
          },
          "merchant_identity": {
            "type": "string",
            "example": "IDxxxxxxxxxxxxxxxxxxxxxx",
            "description": "The ID of the `Identity` resource used by the `Merchant` the `Authorization` was processed under."
          },
          "messages": {
            "type": "array",
            "description": "Message field that provides additional details. This field is typically **null**.",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "network_details": {
            "type": "object",
            "description": "Contains network-specific fields used by issuers to identify transactions.",
            "nullable": true,
            "properties": {
              "brand": {
                "type": "string",
                "description": "Card brand associated with the saved payment instrument.",
                "example": "VISA"
              },
              "authorization_code": {
                "type": "string",
                "description": "Code returned by the issuing bank when a transaction is authorized.",
                "example": 82533
              }
            }
          },
          "raw": {
            "$ref": "#/components/schemas/raw"
          },
          "receipt_last_printed_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the receipt was last printed.",
            "nullable": true
          },
          "security_code_verification": {
            "type": "string",
            "description": "Details the results of the Security Code Verification che",
            "nullable": true
          },
          "source": {
            "$ref": "#/components/schemas/source"
          },
          "state": {
            "type": "string",
            "enum": [
              "CANCELED",
              "PENDING",
              "FAILED",
              "SUCCEEDED",
              "UNKNOWN"
            ],
            "description": "The state of the `Authorization`."
          },
          "supplemental_fee": {
            "type": "integer",
            "format": "int64",
            "description": "Amount in cents for which an additional fee will be created in addition to any fees created from the assigned fee profile.",
            "nullable": true
          },
          "tags": {
            "$ref": "#/components/schemas/tags"
          },
          "trace_id": {
            "type": "string",
            "description": "Trace ID of the `Authorization`. The processor sends back the `trace_id` so you can track the authorization end-to-end."
          },
          "transfer": {
            "type": "string",
            "example": "TRxxxxxxxxxxxxxxxxxx",
            "description": "The ID of the `transfer` resource that gets created when the `Authorization` moves to **SUCCEEDED**.",
            "nullable": true
          },
          "void_state": {
            "type": "string",
            "description": "The state of the void attempt for the `Authorization`.",
            "enum": [
              "UNATTEMPTED",
              "PENDING",
              "SUCCEEDED"
            ]
          },
          "_links": {
            "type": "object",
            "properties": {
              "self": {
                "$ref": "#/components/schemas/self"
              },
              "application": {
                "$ref": "#/components/schemas/application_link"
              },
              "device": {
                "type": "object",
                "description": "Link to the `Device` the request was made under.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "merchant_identity": {
                "$ref": "#/components/schemas/merchant_identity"
              },
              "transfer": {
                "type": "object",
                "description": "Link to the `Transfer` created when the `Authorization` moves to **SUCCEEDED**.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "transfers": {
                "$ref": "#/components/schemas/transfers"
              }
            }
          }
        }
      }
    }
  }
}
```

## Capture an Authorization with Level 2 / Level 3 processing

Finix will automatically include the Level 2 / Level 3 data with the [capture](/api/authorizations/captureauthorization) request.

## Ineligible Merchants

Specific businesses are excluded from processing Level 2 and Level 3 transactions.

If a merchant has one of the following Merchant Category Codes (MCC), they are not eligible to process Level 2 / Level 3 transactions:

| MCC Code | Merchant Description |
|  --- | --- |
| **3000-3299, 4511** | Airlines/Passenger Transport |
| **3351-3500, 7512** | Car Rentals/Auto Rental |
| **4411** | Cruise Lines |
| **5962, 5966, 5967** | High Risk Direct Marketing |
| **3501-4010, 7011** | Hotels/Lodging |
| **4112** | Passenger Railways |
| **5812, 5814** | Restaurants |
| **4722** | Travel Agents |
| **7513** | Truck and Utility Trailer Rentals |


## Data Quality Best Practices

The Level 2 / Level 3 processing data you submit should be accurate and of high quality. The card network's validation technology will identify generic descriptions, placeholder data, and artificially generated content. The data must be real, accurate, and descriptive of the actual products or services being sold.

The examples below are meant to help point you in the right direction, but they are not exhaustive. Ultimately, the card network decides whether the data a merchant submits qualifies.

| Finix Line Item Field | Card Network Recommendation | Avoid |
|  --- | --- | --- |
| `item_description` | Must provide meaningful information about purchased items/services. | Do not provide merchant name, single characters, or generic descriptions. |
| `merchant_product_code` | Typically the SKU or identifier by which the merchant tracks and prices the item or service. Must always be provided for every line item. The product code can be the merchant's, manufacturer's, or buyer's product code. This field must provide information about the purchase, not the customer. | Do not use erroneous data, such as the card product or MCC. |