# Create a Checkout Form

Create a  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"

## Request fields (application/json):

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

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

  - `is_multiple_use` (boolean)
    If set to , the checkout form can be used for multiple purchases.

  - `allowed_payment_methods` (array, required)
    Payment methods allowed on the checkout form.

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

  - `items` (array)
    An itemized list of products/services.

  - `buyer_details` (object)
    Object containing details about the buyer. This object is only used for  checkout forms.

  - `buyer_details.identity_id` (string)
    The   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` (string,null)
    Shipping or mailling address of the buyer.

  - `buyer_details.billing_address` (string,null)
    Billing address of the buyer.

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

  - `amount_details` (object)
    Object containing details about the amount getting charged.

  - `amount_details.amount_type` (string)
    Add additional details noting if the price is discounted or on sale.

  - `amount_details.total_amount` (integer)
    Total amount of the transaction.

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

  - `amount_details.min_amount` (integer,null)
    Min amount allowed for  amount links.

  - `amount_details.max_amount` (integer,null)
    Max amount allowed for  amount links.

  - `amount_details.amount_breakdown` (object)
    Breakdown of the .

  - `amount_details.amount_breakdown.subtotal_amount` (integer)
    Subtotal amount before tax and other fees.

  - `amount_details.amount_breakdown.shipping_amount` (integer)
    Shipping amount.

  - `amount_details.amount_breakdown.estimated_tax_amount` (integer)
    Estimated tax amount.

  - `amount_details.amount_breakdown.discount_amount` (integer)
    Discount amount in cents.

  - `amount_details.amount_breakdown.tip_amount` (integer)
    Tip amount in cents.

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

The following rules apply:

- The  must be enabled to charge these surcharges by setting the appropriate flags for each applicable surcharge to  using the PUT  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.

  - `branding` (object)
    Object containing branding details for the checkout form.

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

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

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

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

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

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

  - `additional_details` (object)
    Object containing additional details about the checkout form.

  - `additional_details.collect_name` (boolean)
    Collect email address from the payment link.

  - `additional_details.collect_email` (boolean)
    Collect email address from the payment link.

  - `additional_details.collect_phone_number` (boolean)
    Collect phone number from the payment link.

  - `additional_details.collect_billing_address` (boolean)
    Collect billing address from the payment link. Defaults to .

  - `additional_details.collect_shipping_address` (boolean)
    Collect shipping address from the payment link.

  - `additional_details.success_return_url` (string)
    URL to redirect the user to, after the payment is successful.

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

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

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

  - `additional_details.expiration_in_minutes` (integer)
    Details how long (in minutes) the payment link is valid for.

  - `tags` (object,null)
    Include up to 50  pairs to annotate requests with custom metadata.
- Maximum character length for individual  is 40.
- Maximum character length for individual  is 500.
(For example, , , )

## Response 200 fields (application/json):

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

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

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

  - `application_id` (string)
    The ID of the  that the  was created under.

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

  - `nickname` (string)
    A human-readable name for the resource.
    Example: "super important thing"

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

  - `allowed_payment_methods` (array)
    Payment methods allowed on the checkout form.

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

  - `items` (array)
    An itemized list of products/services.

  - `buyer_details` (string,null)
    Object containing details about the buyer. This object is only used for  checkout forms.

  - `amount_details` (object)
    Object containing details about the amount getting charged.

  - `amount_details.amount_type` (string)
    Add additional details noting if the price is discounted or on sale.

  - `amount_details.total_amount` (integer)
    Total amount of the transaction.

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

  - `amount_details.min_amount` (integer,null)
    Min amount allowed for  amount links.

  - `amount_details.max_amount` (integer,null)
    Max amount allowed for  amount links.

  - `amount_details.amount_breakdown` (object)
    Breakdown of the .

  - `amount_details.amount_breakdown.subtotal_amount` (integer)
    Subtotal amount before tax and other fees.

  - `amount_details.amount_breakdown.shipping_amount` (integer)
    Shipping amount.

  - `amount_details.amount_breakdown.estimated_tax_amount` (integer)
    Estimated tax amount.

  - `amount_details.amount_breakdown.discount_amount` (integer)
    Discount amount in cents.

  - `amount_details.amount_breakdown.tip_amount` (integer)
    Tip amount in cents.

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

The following rules apply:

- The  must be enabled to charge these surcharges by setting the appropriate flags for each applicable surcharge to  using the PUT  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.

  - `branding` (object)
    Object containing branding details for the checkout form.

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

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

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

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

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

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

  - `additional_details` (object)
    Object containing additional details about the checkout form.

  - `additional_details.collect_name` (boolean)
    Collect email address from the payment link.

  - `additional_details.collect_email` (boolean)
    Collect email address from the payment link.

  - `additional_details.collect_phone_number` (boolean)
    Collect phone number from the payment link.

  - `additional_details.collect_billing_address` (boolean)
    Collect billing address from the payment link. Defaults to .

  - `additional_details.collect_shipping_address` (boolean)
    Collect shipping address from the payment link.

  - `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.success_return_url` (string)
    URL to redirect the user to, after the payment is successful.

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

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

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

  - `additional_details.expiration_in_minutes` (integer)
    Details how long (in minutes) the payment link is valid for.

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

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

  - `tags` (object,null)
    Include up to 50  pairs to annotate requests with custom metadata.
- Maximum character length for individual  is 40.
- Maximum character length for individual  is 500.
(For example, , , )

  - `_links` (object)
    For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these  to make your follow-up requests and quickly access relevant IDs.

  - `_links.next` (object)
    Link to the next page of entries.

  - `_links.next.href` (string)

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

## Response 401 fields (application/json):

  - `total` (integer)

  - `_embedded` (object)

  - `_embedded.errors` (array)

  - `_embedded.errors.code` (string)
    Enum: "UNKNOWN"

  - `_embedded.errors.logref` (object)

  - `_embedded.errors.message` (string)

  - `_embedded.errors._links` (object)

  - `_embedded.errors._links.self` (object)

  - `_embedded.errors._links.self.href` (string)

  - `_embedded.errors._links.source` (object)

## Response 404 fields (application/json):

  - `total` (integer)

  - `_embedded` (object)

  - `_embedded.errors` (array)

  - `_embedded.errors.code` (string)
    Enum: "NOT_FOUND"

  - `_embedded.errors.logref` (object)

  - `_embedded.errors.message` (string)

  - `_embedded.errors._links` (object)

  - `_embedded.errors._links.source` (object)

  - `_embedded.errors._links.source.href` (string)

## Response 406 fields (application/json):

  - `total` (integer)

  - `_embedded` (object)

  - `_embedded.errors` (array)

  - `_embedded.errors.code` (string)
    Enum: "NOT_FOUND"

  - `_embedded.errors.logref` (object)

  - `_embedded.errors.message` (string)

  - `_embedded.errors._links` (object)

  - `_embedded.errors._links.source` (object)

  - `_embedded.errors._links.source.href` (string)

## Response 422 fields (application/json):

  - `total` (integer)

  - `_embedded` (object)

  - `_embedded.errors` (array)

  - `_embedded.errors.code` (string)
    Enum: "INVALID_FIELD"

  - `_embedded.errors.field` (string)

  - `_embedded.errors.logref` (object)

  - `_embedded.errors.message` (string)

  - `_embedded.errors._links` (object)

  - `_embedded.errors._links.source` (object)

  - `_embedded.errors._links.source.href` (string)