# Create a Checkout Form

Create a Checkout Form to accept the details of buyers. 

Related guides: Checkout Forms.

Endpoint: POST /checkout_forms
Version: 2022-02-01
Security: BasicAuth

## Header parameters:

  - `Finix-Version` (string)
    Specify the API version of your request. For more details, see Versioning.
    Example: "2022-02-01"

  - `Content-Type` (string)
    The data type being sent in the request body must be application/json.
    Example: "application/json"

## Request fields (application/json):

  - `merchant_id` (string, required)
    The ID of the Merchant the payment is getting created under.   Only approved Merchants with one of the following processors can create checkout pages: DUMMY_V1 or FINIX_V1.

  - `payment_frequency` (string, required)
    Details if a payment created from a checkout form is: ONE\_TIMERECURRING At this time, only ONE\_TIME is supported.

  - `allowed_payment_methods` (array, required)
    The allowed payment methods.
    Enum: "APPLE_PAY", "BANK_ACCOUNT", "GOOGLE_PAY", "PAYMENT_CARD"

  - `attempt_level_two_level_three_payment` (boolean)
    Setting this field to true enables Level 2/Level 3 data collection for card payments.

  - `nickname` (string, required)
    Descriptor name of the checkout form.

  - `is_authorization` (boolean)
    When set to true, submitting the Checkout Form creates an Authorization instead of a Transfer.

  - `items` (array)
    An itemized list of products/services. This field is required for the transaction to qualify for Level 3 processing.

  - `items.description` (string)
    A item description. This field is required for the transaction to qualify for Level 3 processing.

  - `items.image_details` (object)
    Product/service image locations.

  - `items.image_details.primary_image_url` (string)
    The location of a item image.

  - `items.image_details.alternative_image_urls` (array)
    The locations of backup images if there is an issue with the primary image.

  - `items.item_details` (object)
    Additional details about the item. This object and all of its fields are required for the transaction to qualify for Level 3 processing.

  - `items.item_details.commodity_code` (string, required)
    Commodity code for the item.
    Example: "175-62-20"

  - `items.item_details.merchant_product_code` (string, required)
    Merchant's product code for the item.
    Example: "1149611"

  - `items.item_details.unit_of_measure` (string, required)
    Unit of measure for the item.
    Example: "BX"

  - `items.item_details.cost_per_unit` (integer, required)
    Cost per unit in cents.
    Example: 500

  - `items.name` (string)
    The item name.

  - `items.price_details` (object)
    Additional details about the price. This field is required for the transaction to qualify for Level 3 processing.

  - `items.price_details.amount_excluding_sales_tax` (integer)
    The amount excluding sales tax. This field is required for the transaction to qualify for Level 3 processing.

  - `items.price_details.sale_amount` (integer)
    The on-sale price of the item if it is different from the regular_amount.

  - `items.price_details.currency` (string)
    ISO 4217 3-letter currency code.
    Enum: "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYR", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "UYI", "UYU", "UZS", "VEF", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "XSU", "XTS", "XUA", "XXX", "YER", "ZAR", "ZMW", "ZWL"

  - `items.price_details.price_type` (string)
    Whether the price is on-sale (PROMOTIONAL) or the normal price (REGULAR).
    Enum: "PROMOTIONAL", "REGULAR"

  - `items.price_details.regular_amount` (integer)
    The standard price of the item without any adjustments applied (e.g. discounts, taxes, sales). This field is required for the transaction to qualify for Level 3 processing.

  - `items.price_details.item_discount_amount` (integer)
    The item discount. If Level 2/3 processing is enabled, this optional field must have a value of at least 0.

  - `items.quantity` (integer)
    The item quantity. This field is required for the transaction to qualify for Level 3 processing.

  - `buyer_details` (object)
    Object containing details about the user. This object is only valid when payment_frequency is ONE_TIME.

  - `buyer_details.customer_reference_number` (string)
    The customer reference for the purchase (max 17 characters). 

Note:
- For Mastercard, this field is required for the transaction to qualify for Level 2 / Level 3 processing. 
- For Visa, after April 17, 2026, this field no longer qualifies for lower interchange. You must include an itemized list of products/services (items array) for Level 3 processing.

  - `buyer_details.identity_id` (string)
    The Identity id of the buyer.

  - `buyer_details.first_name` (string)
    First name of the buyer.

  - `buyer_details.last_name` (string)
    Last name of the buyer.

  - `buyer_details.email` (string,null)
    Email address of the buyer.

  - `buyer_details.shipping_address` (object)

  - `buyer_details.shipping_address.line1` (string,null, required)
    First line of the address (max 35 characters).

  - `buyer_details.shipping_address.line2` (string,null)
    Second line of the address (max 35 characters).

  - `buyer_details.shipping_address.city` (string,null, required)
    City (max 20 characters).

  - `buyer_details.shipping_address.region` (string,null, required)
    2-letter State code.

  - `buyer_details.shipping_address.postal_code` (string,null, required)
    Zip or Postal code (max 7 characters).

  - `buyer_details.shipping_address.country` (string,null, required)
    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"

  - `buyer_details.billing_address` (object)

  - `buyer_details.billing_address.line1` (string,null, required)
    First line of the address (max 35 characters).

  - `buyer_details.billing_address.line2` (string,null)
    Second line of the address (max 35 characters).

  - `buyer_details.billing_address.city` (string,null, required)
    City (max 20 characters).

  - `buyer_details.billing_address.region` (string,null, required)
    2-letter State code.

  - `buyer_details.billing_address.postal_code` (string,null, required)
    Zip or Postal code (max 7 characters).

  - `buyer_details.billing_address.country` (string,null, required)
    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"

  - `buyer_details.phone_number` (string,null)
    Phone number of the buyer.

  - `amount_details` (object, required)
    Object containing amount details.

  - `amount_details.amount_breakdown` (object)
    The individual charges/fees that add up to the total amount. This field is required for the transaction to qualify for Level 2 or Level 3 processing.

  - `amount_details.amount_breakdown.additional_buyer_charges` (object,null)
    Additional charges will be incurred by the buyer. 

The following rules apply:

- 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.
- Only _one_ of the following charges can be applied during creation.

  - `amount_details.amount_breakdown.additional_buyer_charges.convenience_amount` (integer,null)
    A convenience fee to charge the buyer for the transaction. This object property is mutually exclusive.

  - `amount_details.amount_breakdown.additional_buyer_charges.rent_surcharge_amount` (integer,null)
    A rent surcharge to charge the buyer for the transaction. This object property is mutually exclusive.

  - `amount_details.amount_breakdown.additional_buyer_charges.surcharge_amount` (integer,null)
    A surcharge amount to charge the buyer for the transaction. This object property is mutually exclusive.

  - `amount_details.amount_breakdown.customs_duty_amount` (integer)
    The duty in cents on the total payment amount. This field is required for level 3 processing, and if provided, it must have a value of at least 0.

  - `amount_details.amount_breakdown.discount_amount` (integer)
    A reduction applied to the total amount. If Level 2/3 processing is enabled, this optional field must have a value of at least 0.

  - `amount_details.amount_breakdown.estimated_tax_amount` (integer)
    The estimated amount of tax applied to the order. This field is optional for Level 2 processing. In order for a transaction to qualify for Level 3 processing, this field must omitted or set to null.

  - `amount_details.amount_breakdown.subtotal_amount` (integer)
    The subtotal amount before any taxes, shipping, or additional charges are applied.

  - `amount_details.amount_breakdown.shipping_amount` (integer)
    The amount charged for shipping the items in the order. If Level 2/3 processing is enabled, this optional field must have a value of at least 0.

  - `amount_details.amount_breakdown.tax_exempt` (boolean)
    For tax exempt payments set to true. This field is used for Level 2/3 processing when enabled, but it is optional.

  - `amount_details.amount_breakdown.tip_amount` (integer)
    The tip amount included in the order total.

  - `amount_details.amount_type` (string)
    The supported enums are:

FIXED - A set amount that cannot be altered by the user. 
VARIABLE - Allows the user to set their own amount, provided it adheres to the minimum and maximum limits (min_amount and max_amount, respectively).
    Enum: "FIXED", "VARIABLE"

  - `amount_details.currency` (string)
    3-letter ISO code designating the currency of the Transfers (e.g. USD).

  - `amount_details.max_amount` (integer,null)
    Maximum amount allowed when the amount is VARIABLE. This field is required when amount_type is VARIABLE.

  - `amount_details.min_amount` (integer,null)
    Minimum amount allowed when the amount is VARIABLE. This field is required when amount_type is VARIABLE.

  - `amount_details.surcharge_basis_points` (integer,null)
    The surcharge amount in basis points to add to the transfer when a payment is submitted. 100 basis points = 1%.

- For USA merchants, must be greater than 0 and less than or equal to 300.
- For CAN merchants, must be greater than 0 and less than or equal to 240.
- If present, additional_buyer_charges must be null.

The surcharge applies only to credit card payments. The surcharge amount appears in the resulting Transfer and Transfer Attempt resources under additional_buyer_charges.surcharge_amount.
    Example: 200

  - `amount_details.total_amount` (integer)
    The total amount.

  - `branding` (object, required)

  - `branding.accent_color` (string, required)
    Hex code of the accent color.
    Example: "#F2F2F2"

  - `branding.brand_color` (string, required)
    Hex code of branding color.
    Example: "#F2F2F2"

  - `branding.button_font_color` (string,null)
    Hex code of the button font color.

  - `branding.icon` (string, required)
    URL for the icon of the payment link.

  - `branding.logo` (string, required)
    URL of the logo for the payment link.

  - `branding.logo_alternative_text` (string,null)
    Alternate text displayed if the logo image cannot display.

  - `additional_details` (object, required)
    Object containing additional details.

  - `additional_details.collect_billing_address` (boolean)
    The collected billing address. Defaults to false.

  - `additional_details.collect_email` (boolean)
    The collected email address.

  - `additional_details.collect_name` (boolean)
    The collected name.

  - `additional_details.collect_shipping_address` (boolean)
    The collected shipping address.

  - `additional_details.expiration_in_minutes` (integer)
    The expiration in minutes. The maximum value is 1576800 minutes (3 years).

  - `additional_details.expired_session_url` (string)
    A URL to redirect the user if their session times out.

  - `additional_details.receipt_requested_delivery_methods` (array)
    A list of requested delivery methods. Each method specifies 
the type of delivery and the destination(s) where the receipt should be sent.

  - `additional_details.receipt_requested_delivery_methods.type` (string, required)
    The method of receipt delivery.
    Enum: "EMAIL", "SMS", "PRINT"

  - `additional_details.receipt_requested_delivery_methods.destinations` (array, required)
    A list of destination addresses or identifiers where the receipt should be sent.

  - `additional_details.send_receipt` (boolean)
    Whether to send the user a receipt.

  - `additional_details.statement_descriptor` (string,null)
    The description of the Merchant that appears on the buyer's bank or card statement.

  - `additional_details.success_return_url` (string)
    The redirect URL for a successful outcome.

  - `additional_details.terms_of_service_url` (string, required)
    Your Terms of Service URL.

  - `additional_details.unsuccessful_return_url` (string)
    The redirect URL for an unsuccessful outcome.

  - `additional_details.collect_phone` (boolean)
    The collected phone number.

  - `additional_details.cart_return_url` (string)
    URL to redirect the user back to their cart.

  - `split_transfers` (array,null)
    An array used to detail how funds from the Transfer will split and the amount Merchants receive.

Rules:
- The combined amounts under split_transfers must be equal to the amount submitted in the parent Transfer.
- Merchants can be based in the United States or Canada.
- The amount type must be FIXED.

For more information, see:
- [Split Transactions](../../../../guides/online-payments/payment-features/split-transactions).

  - `split_transfers.merchant` (string)
    - The ID of the Merchant that will receive the specified amount under the split_transfers object.
- In Split Transactions, the merchants specified in the split_transfers object are the ancillary merchants.

  - `split_transfers.amount` (integer)
    - The amount of funds that get split and paid out to the specified Merchant.
- Must be less than or equal to the amount of the Transfer.

  - `split_transfers.fee` (integer)
    - A processing fee is deducted when the Merchant receives their payout, specified in cents.
- Must be less than or equal to the total amount being split for the designated Merchant. 
- By default, this fee is set to 0.

  - `split_transfers.tags` (object,null)
    Include up to 50 key: value pairs to annotate requests with custom metadata.
- Maximum character length for individual keys is 40.
- Maximum character length for individual values is 500.
(For example, order_number: 25, item_type: produce, department: sales)

  - `tags` (object,null)
    Include up to 50 key: value pairs to annotate requests with custom metadata.
- Maximum character length for individual keys is 40.
- Maximum character length for individual values is 500.
(For example, order_number: 25, item_type: produce, department: sales)

## Response 201 fields (application/json):

  - `id` (string)
    The ID of the resource.

  - `created_at` (string)
    Timestamp of when the object was created.

  - `updated_at` (string)
    Timestamp of when the object was last updated.

  - `application` (string)
    ID of the Application the resource was created under.

  - `merchant_id` (string)
    The ID of the Merchant resource the payment_link was created for and will settle under.

  - `nickname` (string)
    A human-readable name for the resource.

  - `payment_frequency` (string)
    Details if a payment created from a checkout form is: ONE\_TIMERECURRING At this time, only ONE\_TIME is supported.

  - `allowed_payment_methods` (array)
    The allowed payment methods.
    Enum: "APPLE_PAY", "BANK_ACCOUNT", "GOOGLE_PAY", "PAYMENT_CARD"

  - `state` (string)
    The state of the Checkout Form.

  - `is_authorization` (boolean)
    When set to true, submitting the Checkout Form creates an Authorization instead of a Transfer.

  - `items` (array)
    An itemized list of products/services. This field is required for the transaction to qualify for Level 3 processing.

  - `items.description` (string)
    A item description. This field is required for the transaction to qualify for Level 3 processing.

  - `items.image_details` (object)
    Product/service image locations.

  - `items.image_details.primary_image_url` (string)
    The location of a item image.

  - `items.image_details.alternative_image_urls` (array)
    The locations of backup images if there is an issue with the primary image.

  - `items.item_details` (object)
    Additional details about the item. This object and all of its fields are required for the transaction to qualify for Level 3 processing.

  - `items.item_details.commodity_code` (string, required)
    Commodity code for the item.
    Example: "175-62-20"

  - `items.item_details.merchant_product_code` (string, required)
    Merchant's product code for the item.
    Example: "1149611"

  - `items.item_details.unit_of_measure` (string, required)
    Unit of measure for the item.
    Example: "BX"

  - `items.item_details.cost_per_unit` (integer, required)
    Cost per unit in cents.
    Example: 500

  - `items.name` (string)
    The item name.

  - `items.price_details` (object)
    Additional details about the price. This field is required for the transaction to qualify for Level 3 processing.

  - `items.price_details.amount_excluding_sales_tax` (integer)
    The amount excluding sales tax. This field is required for the transaction to qualify for Level 3 processing.

  - `items.price_details.sale_amount` (integer)
    The on-sale price of the item if it is different from the regular_amount.

  - `items.price_details.currency` (string)
    ISO 4217 3-letter currency code.
    Enum: "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYR", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "UYI", "UYU", "UZS", "VEF", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "XSU", "XTS", "XUA", "XXX", "YER", "ZAR", "ZMW", "ZWL"

  - `items.price_details.price_type` (string)
    Whether the price is on-sale (PROMOTIONAL) or the normal price (REGULAR).
    Enum: "PROMOTIONAL", "REGULAR"

  - `items.price_details.regular_amount` (integer)
    The standard price of the item without any adjustments applied (e.g. discounts, taxes, sales). This field is required for the transaction to qualify for Level 3 processing.

  - `items.price_details.item_discount_amount` (integer)
    The item discount. If Level 2/3 processing is enabled, this optional field must have a value of at least 0.

  - `items.quantity` (integer)
    The item quantity. This field is required for the transaction to qualify for Level 3 processing.

  - `buyer_details` (object)
    Object containing details about the user. This object is only valid when payment_frequency is ONE_TIME.

  - `buyer_details.customer_reference_number` (string)
    The customer reference for the purchase (max 17 characters). 

Note:
- For Mastercard, this field is required for the transaction to qualify for Level 2 / Level 3 processing. 
- For Visa, after April 17, 2026, this field no longer qualifies for lower interchange. You must include an itemized list of products/services (items array) for Level 3 processing.

  - `buyer_details.identity_id` (string)
    The Identity id of the buyer.

  - `buyer_details.first_name` (string)
    First name of the buyer.

  - `buyer_details.last_name` (string)
    Last name of the buyer.

  - `buyer_details.email` (string,null)
    Email address of the buyer.

  - `buyer_details.shipping_address` (object)

  - `buyer_details.shipping_address.line1` (string,null, required)
    First line of the address (max 35 characters).

  - `buyer_details.shipping_address.line2` (string,null)
    Second line of the address (max 35 characters).

  - `buyer_details.shipping_address.city` (string,null, required)
    City (max 20 characters).

  - `buyer_details.shipping_address.region` (string,null, required)
    2-letter State code.

  - `buyer_details.shipping_address.postal_code` (string,null, required)
    Zip or Postal code (max 7 characters).

  - `buyer_details.shipping_address.country` (string,null, required)
    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"

  - `buyer_details.billing_address` (object)

  - `buyer_details.billing_address.line1` (string,null, required)
    First line of the address (max 35 characters).

  - `buyer_details.billing_address.line2` (string,null)
    Second line of the address (max 35 characters).

  - `buyer_details.billing_address.city` (string,null, required)
    City (max 20 characters).

  - `buyer_details.billing_address.region` (string,null, required)
    2-letter State code.

  - `buyer_details.billing_address.postal_code` (string,null, required)
    Zip or Postal code (max 7 characters).

  - `buyer_details.billing_address.country` (string,null, required)
    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"

  - `buyer_details.phone_number` (string,null)
    Phone number of the buyer.

  - `amount_details` (object)
    Object containing amount details.

  - `amount_details.amount_breakdown` (object)
    The individual charges/fees that add up to the total amount. This field is required for the transaction to qualify for Level 2 or Level 3 processing.

  - `amount_details.amount_breakdown.additional_buyer_charges` (object,null)
    Additional charges will be incurred by the buyer. 

The following rules apply:

- 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.
- Only _one_ of the following charges can be applied during creation.

  - `amount_details.amount_breakdown.additional_buyer_charges.convenience_amount` (integer,null)
    A convenience fee to charge the buyer for the transaction. This object property is mutually exclusive.

  - `amount_details.amount_breakdown.additional_buyer_charges.rent_surcharge_amount` (integer,null)
    A rent surcharge to charge the buyer for the transaction. This object property is mutually exclusive.

  - `amount_details.amount_breakdown.additional_buyer_charges.surcharge_amount` (integer,null)
    A surcharge amount to charge the buyer for the transaction. This object property is mutually exclusive.

  - `amount_details.amount_breakdown.customs_duty_amount` (integer)
    The duty in cents on the total payment amount. This field is required for level 3 processing, and if provided, it must have a value of at least 0.

  - `amount_details.amount_breakdown.discount_amount` (integer)
    A reduction applied to the total amount. If Level 2/3 processing is enabled, this optional field must have a value of at least 0.

  - `amount_details.amount_breakdown.estimated_tax_amount` (integer)
    The estimated amount of tax applied to the order. This field is optional for Level 2 processing. In order for a transaction to qualify for Level 3 processing, this field must omitted or set to null.

  - `amount_details.amount_breakdown.subtotal_amount` (integer)
    The subtotal amount before any taxes, shipping, or additional charges are applied.

  - `amount_details.amount_breakdown.shipping_amount` (integer)
    The amount charged for shipping the items in the order. If Level 2/3 processing is enabled, this optional field must have a value of at least 0.

  - `amount_details.amount_breakdown.tax_exempt` (boolean)
    For tax exempt payments set to true. This field is used for Level 2/3 processing when enabled, but it is optional.

  - `amount_details.amount_breakdown.tip_amount` (integer)
    The tip amount included in the order total.

  - `amount_details.amount_type` (string)
    The supported enums are:

FIXED - A set amount that cannot be altered by the user. 
VARIABLE - Allows the user to set their own amount, provided it adheres to the minimum and maximum limits (min_amount and max_amount, respectively).
    Enum: "FIXED", "VARIABLE"

  - `amount_details.currency` (string)
    3-letter ISO code designating the currency of the Transfers (e.g. USD).

  - `amount_details.max_amount` (integer,null)
    Maximum amount allowed when the amount is VARIABLE. This field is required when amount_type is VARIABLE.

  - `amount_details.min_amount` (integer,null)
    Minimum amount allowed when the amount is VARIABLE. This field is required when amount_type is VARIABLE.

  - `amount_details.surcharge_basis_points` (integer,null)
    The surcharge amount in basis points to add to the transfer when a payment is submitted. 100 basis points = 1%.

- For USA merchants, must be greater than 0 and less than or equal to 300.
- For CAN merchants, must be greater than 0 and less than or equal to 240.
- If present, additional_buyer_charges must be null.

The surcharge applies only to credit card payments. The surcharge amount appears in the resulting Transfer and Transfer Attempt resources under additional_buyer_charges.surcharge_amount.
    Example: 200

  - `amount_details.total_amount` (integer)
    The total amount.

  - `attempt_level_two_level_three_payment` (boolean)
    Setting this field to true enables Level 2/Level 3 data collection for card payments.

  - `branding` (object)

  - `branding.accent_color` (string, required)
    Hex code of the accent color.
    Example: "#F2F2F2"

  - `branding.brand_color` (string, required)
    Hex code of branding color.
    Example: "#F2F2F2"

  - `branding.button_font_color` (string,null)
    Hex code of the button font color.

  - `branding.icon` (string, required)
    URL for the icon of the payment link.

  - `branding.logo` (string, required)
    URL of the logo for the payment link.

  - `branding.logo_alternative_text` (string,null)
    Alternate text displayed if the logo image cannot display.

  - `additional_details` (object)
    Object containing additional details.

  - `additional_details.collect_billing_address` (boolean)
    The collected billing address. Defaults to false.

  - `additional_details.collect_email` (boolean)
    The collected email address.

  - `additional_details.collect_name` (boolean)
    The collected name.

  - `additional_details.collect_shipping_address` (boolean)
    The collected shipping address.

  - `additional_details.expiration_in_minutes` (integer)
    The expiration in minutes. The maximum value is 1576800 minutes (3 years).

  - `additional_details.expired_session_url` (string)
    A URL to redirect the user if their session times out.

  - `additional_details.receipt_requested_delivery_methods` (array)
    A list of requested delivery methods. Each method specifies 
the type of delivery and the destination(s) where the receipt should be sent.

  - `additional_details.receipt_requested_delivery_methods.type` (string, required)
    The method of receipt delivery.
    Enum: "EMAIL", "SMS", "PRINT"

  - `additional_details.receipt_requested_delivery_methods.destinations` (array, required)
    A list of destination addresses or identifiers where the receipt should be sent.

  - `additional_details.send_receipt` (boolean)
    Whether to send the user a receipt.

  - `additional_details.statement_descriptor` (string,null)
    The description of the Merchant that appears on the buyer's bank or card statement.

  - `additional_details.success_return_url` (string)
    The redirect URL for a successful outcome.

  - `additional_details.terms_of_service_url` (string, required)
    Your Terms of Service URL.

  - `additional_details.unsuccessful_return_url` (string)
    The redirect URL for an unsuccessful outcome.

  - `additional_details.collect_phone` (boolean)
    The collected phone number.

  - `additional_details.cart_return_url` (string)
    URL to redirect the user back to their cart.

  - `link_url` (string)
    The URL of the user's Finix Onboarding Form. Users can use the link_url to return to the form until the link expires.

  - `link_expires_at` (string)
    Timestamp of when the Checkout  will expire.

  - `split_transfers` (array,null)
    An array used to detail how funds from the Transfer will split and the amount Merchants receive.

Rules:
- The combined amounts under split_transfers must be equal to the amount submitted in the parent Transfer.
- Merchants can be based in the United States or Canada.
- The amount type must be FIXED.

For more information, see:
- [Split Transactions](../../../../guides/online-payments/payment-features/split-transactions).

  - `split_transfers.merchant` (string)
    - The ID of the Merchant that will receive the specified amount under the split_transfers object.
- In Split Transactions, the merchants specified in the split_transfers object are the ancillary merchants.

  - `split_transfers.amount` (integer)
    - The amount of funds that get split and paid out to the specified Merchant.
- Must be less than or equal to the amount of the Transfer.

  - `split_transfers.fee` (integer)
    - A processing fee is deducted when the Merchant receives their payout, specified in cents.
- Must be less than or equal to the total amount being split for the designated Merchant. 
- By default, this fee is set to 0.

  - `split_transfers.tags` (object,null)
    Include up to 50 key: value pairs to annotate requests with custom metadata.
- Maximum character length for individual keys is 40.
- Maximum character length for individual values is 500.
(For example, order_number: 25, item_type: produce, department: sales)

  - `tags` (object,null)
    Include up to 50 key: value pairs to annotate requests with custom metadata.
- Maximum character length for individual keys is 40.
- Maximum character length for individual values is 500.
(For example, order_number: 25, item_type: produce, department: sales)

  - `_links` (object)

  - `_links.self` (object)
    Link to the resource that was used in the request.

  - `_links.self.href` (string)

## Response 400 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 401 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 403 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 406 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 422 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.