Checkout Pages

Use Finix to build a custom low-code checkout form.

Checkout Pages

Using checkout pages you can quickly accept payments from buyers with minimal development work. Checkout pages are a low-code solution that enables you to create a customizable payment page where buyers can easily enter their payment details and submit a payment on both desktop and mobile devices.

Checkout pages are only available via the Finix API. If you want to create a similar experience on the Dashboard, look into our Payment Links.

Checkout Form

Buyer Perspective

  1. When your buyers are ready to complete their payment, create a checkout_form
  2. The checkout_form provides a URL you can send to buyers to redirect them to a Finix checkout form.
  3. Buyers enter their payment details into the checkout form and complete their payment.

Checkout Form - Diagram

Supported Payment Methods

Checkout pages support:

  • Card payments
  • Bank account payments (ACH in USA)

For more details about ACH payments, see ACH Direct Debit.

Expiration

By default, checkout_forms expire after 10 minutes. You can extend the expiration date to a maximum of 3 weeks. Please note the expiration time of the checkout_form must be less than your cart expiration time; otherwise, timeout issues can come up for your buyers when submitting a payment.

checkout_forms can only be used once. After a buyer makes a successful payment, the checkout_form cannot be used again. If a buyer returns to a successful checkout_form link, they'll see a You have already paid message and/or get redirected to a new page.

Finix API

To create a checkout form, include:

  • The ID of the Merchant that the payment will be created under.
  • The amount of the transaction.
  • Any additional URLs (terms of service required).
  • Allowed payment methods.

At this time, only APPROVED Merchants with one of the following processors can create checkout pages:

  • DUMMY_V1
  • LITLE_V1
  • FINIX_V1
Copy
Copied
curl https://finix.sandbox-payments-api.com/checkout_forms \
   -H "Content-Type: application/json" \
   -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
   -X POST \
   -d '{
         "merchant_id": "MUucec6fHeaWo3VHYoSkUySM",
         "payment_frequency": "ONE_TIME",
         "is_multiple_use": false,
         "allowed_payment_methods": [
            "PAYMENT_CARD"
         ],
         "nickname": "string",
         "items": [
            {
                  "image_details": {
                     "primary_image_url": "https://images.unsplash.com/photo-1511499767150-a48a237f0083?q=80&w=2980&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
                     "alternative_image_urls": [
                        "https://google.com/image1",
                        "https://google.com/image2"
                     ]
                  },
                  "description": "These are cool sunglasses",
                  "price_details": {
                     "sale_amount": 4000,
                     "currency": "USD",
                     "price_type": "PROMOTIONAL",
                     "regular_amount": 5000
                  },
                  "quantity": "1"
            }
         ],
         "buyer_details": {
            "identity_id": "IDpYDM7J9n57q849o9E9yNrG",
            "first_name": "Oscar",
            "last_name": "Barillas",
            "email": null,
            "shipping_address": null,
            "billing_address": null,
            "phone_number": null
         },
         "amount_details": {
            "amount_type": "FIXED",
            "total_amount": 5418,
            "currency": "USD",
            "min_amount": null,
            "max_amount": null,
            "amount_breakdown": {
                  "subtotal_amount": 3994,
                  "shipping_amount": 995,
                  "estimated_tax_amount": 429,
                  "discount_amount": "1000",
                  "tip_amount": "1000"
            }
         },
         "branding": {
            "brand_color": "#fbe5d0",
            "accent_color": "#ff4838",
            "logo": "https://s3.amazonaws.com/customer-uploaded-assets-prod/04-12-2023-05_13_37_ACME_logo-01%20%281%29.png",
            "icon": "https://s3.amazonaws.com/customer-uploaded-assets-prod/04-12-2023-05_13_37_ACME_logo-01%20%281%29.png"
         },
         "additional_details": {
            "collect_name": true,
            "collect_email": true,
            "collect_phone_number": true,
            "collect_billing_address": true,
            "collect_shipping_address": true,
            "success_return_url": "https://www.example.com/success/123rw21w.html ",
            "cart_return_url": "https://www.example.com/my_cart.html",
            "expired_session_url": "https://example.com/error.html ",
            "terms_of_service_url": "https://example.com/terms_of_service.html ",
            "expiration_in_minutes": 57680
         }
      }'

Example Response

Copy
Copied
{
  "id" : "checkout_form_c7T8y5Z7Fg1494HwEf2kx",
  "created_at" : "2024-02-02T23:22:01.998681Z",
  "updated_at" : "2024-02-02T23:22:01.998681Z",
  "merchant_id" : "MUucec6fHeaWo3VHYoSkUySM",
  "application_id" : "APgPDQrLD52TYvqazjHJJchM",
  "payment_frequency" : "ONE_TIME",
  "allowed_payment_methods" : [ "PAYMENT_CARD" ],
  "nickname" : "string",
  "state" : "ACTIVE",
  "items" : [ {
    "image_details" : {
      "primary_image_url" : "https://images.unsplash.com/photo-1511499767150-a48a237f0083?q=80&w=2980&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
      "alternative_image_urls" : [ "https://google.com/image1", "https://google.com/image2" ]
    },
    "description" : "These are cool sunglasses",
    "price_details" : {
      "sale_amount" : 4000,
      "currency" : "USD",
      "price_type" : "PROMOTIONAL",
      "regular_amount" : 5000
    },
    "name" : null,
    "quantity" : 1
  } ],
  "buyer_details" : {
    "identity_id" : "IDpYDM7J9n57q849o9E9yNrG",
    "first_name" : "Oscar",
    "last_name" : "Barillas",
    "email" : null,
    "phone" : null,
    "billing_address" : null,
    "shipping_address" : null
  },
  "amount_details" : {
    "amount_type" : "FIXED",
    "total_amount" : 5418,
    "currency" : "USD",
    "min_amount" : null,
    "max_amount" : null,
    "amount_breakdown" : {
      "subtotal_amount" : 3994,
      "shipping_amount" : 995,
      "estimated_tax_amount" : 429,
      "discount_amount" : 1000,
      "tip_amount" : 1000
    }
  },
  "branding" : {
    "brand_color" : "#fbe5d0",
    "accent_color" : "#ff4838",
    "logo" : "https://s3.amazonaws.com/customer-uploaded-assets-prod/04-12-2023-05_13_37_ACME_logo-01%20%281%29.png",
    "icon" : "https://s3.amazonaws.com/customer-uploaded-assets-prod/04-12-2023-05_13_37_ACME_logo-01%20%281%29.png",
    "logo_alternative_text" : null,
    "button_font_color" : null
  },
  "additional_details" : {
    "collect_name" : true,
    "collect_email" : true,
    "collect_phone" : false,
    "collect_billing_address" : true,
    "collect_shipping_address" : true,
    "generate_receipt" : false,
    "success_return_url" : "https://www.example.com/success/123rw21w.html ",
    "cart_return_url" : "https://www.example.com/my_cart.html",
    "expired_session_url" : "https://example.com/error.html ",
    "terms_of_service_url" : "https://example.com/terms_of_service.html ",
    "expiration_in_minutes" : 57680
  },
  "link_url" : "https://finix.sandbox-payments-checkout.com/checkout_form?bearer_token=eyJraWQiOiJEaF9Qem9pODFHOW9BY196bHJHMGJTdHg1c0xEUzk1eFBFTVhpd3RCWkdrIiwidHlwIjoiSldTIiwiYWxnIjoiUlM1MTIifQ.eyJzdWIiOiJVU3NSaHNIWVpHQlBuUXc4Q0J5SnlFUVciLCJhdWQiOiIqLmhvc3RlZC1wYXltZW50cy1odHRwLmZpbml4b3BzLmNvbSIsImlzcyI6ImF1dGhlbnRpY2F0aW9uLnNiLmZpbml4b3BzLmNvbSIsImlhdCI6MTcwNjkxNjEyMiwiZXhwIjoxNzEwMzc2OTIyLCJlbnRpdHlfdHlwZSI6IkNIRUNLT1VUX0ZPUk0iLCJhZGRpdGlvbmFsX2RldGFpbHMiOnsiZXhwaXJlZF9zZXNzaW9uX3VybCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vZXJyb3IuaHRtbCAiLCJzdWNjZXNzX3JldHVybl91cmwiOiJodHRwczovL3d3dy5leGFtcGxlLmNvbS9zdWNjZXNzLzEyM3J3MjF3Lmh0bWwgIiwiZXhwaXJhdGlvbl9pbl9taW51dGVzIjo1NzY4MCwiY29sbGVjdF9iaWxsaW5nX2FkZHJlc3MiOnRydWUsImdlbmVyYXRlX3JlY2VpcHQiOmZhbHNlLCJjb2xsZWN0X25hbWUiOnRydWUsImNvbGxlY3RfZW1haWwiOnRydWUsImNhcnRfcmV0dXJuX3VybCI6Imh0dHBzOi8vd3d3LmV4YW1wbGUuY29tL215X2NhcnQuaHRtbCIsImNvbGxlY3RfcGhvbmUiOmZhbHNlLCJ0ZXJtc19vZl9zZXJ2aWNlX3VybCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdGVybXNfb2Zfc2VydmljZS5odG1sICIsImNvbGxlY3Rfc2hpcHBpbmdfYWRkcmVzcyI6dHJ1ZX0sImJyYW5kaW5nIjp7ImFjY2VudF9jb2xvciI6IiNmZjQ4MzgiLCJidXR0b25fZm9udF9jb2xvciI6bnVsbCwiaWNvbiI6Imh0dHBzOi8vczMuYW1hem9uYXdzLmNvbS9jdXN0b21lci11cGxvYWRlZC1hc3NldHMtcHJvZC8wNC0xMi0yMDIzLTA1XzEzXzM3X0FDTUVfbG9nby0wMSUyMCUyODElMjkucG5nIiwibG9nbyI6Imh0dHBzOi8vczMuYW1hem9uYXdzLmNvbS9jdXN0b21lci11cGxvYWRlZC1hc3NldHMtcHJvZC8wNC0xMi0yMDIzLTA1XzEzXzM3X0FDTUVfbG9nby0wMSUyMCUyODElMjkucG5nIiwiYnJhbmRfY29sb3IiOiIjZmJlNWQwIiwibG9nb19hbHRlcm5hdGl2ZV90ZXh0IjpudWxsfSwiZW50aXR5X2lkIjoiY2hlY2tvdXRfZm9ybV9jN1Q4eTVaN0ZnMTQ5NEh3RWYya3gifQ.KIMR8aWV-7Mlt0YDyhf6i2B1ajx67y2NT36BWPqB8m4QIng5S44retQmMWRQKNKLMLTaSHEM7ifZyIWPt2tvDjf0hOKIAa5h1Btd05vsgzKNVBSClLMqPaTtLcUYYp4WwcGyvCMkjT81p0P34c5dSJ7gfbSyRU5tQjINvuE4v4fVCW2OwqmmAzv-ZC9tp70HRk4e2LGjbwIdVMIHgSorF0XJqGIaeevc_BbK6RiDblripjvXDq_1UpOjQJa1kTbZEfaG3KbVMcgawTSV2I8EHlYGxRdPVk7G9rMhsmGXuuvuhoX2p4zVmRXr_QaZwaqudeama9vlyPbynMGL2ai_xHG7uMtXU7ZAtpRMKjWxSta-5FuoM3lnlFK8iByFsPqGPUZ5Hpmu9BS6N5YqW45ZxbI1XiCTXEQr3r1MiwSXEzqoiP1HT6ReFdoSNZTJ0OTr_LP7eiDCico8CERMffealCCMdvRPEoJQlnE2C7gdjs2W6bZBH9R0L46inaMdLl1Y9d867htqCnBqqiNEi1VCfpPmJcj79hu8BQq9kwA8cSwxVWx981uM-3F9TttS8kFVQOAtZz2QmotdVr_KPngegjB-WTTPkadLU1T2Ksv0O6qk1FxD2KGMMleIQEDfavYsfW5HMRg4lOmc4i56qI8F63e7vhy2YO0VfDd7ZcgFK1o",
  "link_expires_at" : "2024-03-14T00:42:01.99793Z",
  "tags" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/checkout_forms/checkout_form_c7T8y5Z7Fg1494HwEf2kx"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/checkout_forms

Request Arguments

Field Type Description
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, LITLE_V1 or FINIX_V1.
payment_frequency string, required Details if a payment created from a checkout form is:
  • ONE_TIME
  • RECURRING
At this time, only ONE_TIME is supported.
is_multiple_use boolean, optional If set to True, the checkout form can be used for multiple payments.
allowed_payment_methods array, required Payment methods allowed on the checkout form.
nickname string, required Descriptor name of the checkout form.
items object, required Details the items or services used in the payment form.
tags object, optional Key value pair for annotating custom metadata (e.g. order numbers).
buyer object, optional Object containing details about the buyer. This object is only used for SINGLE_USE checkout pages.
amount_details object, optional Object containing details about the amount getting charged by the checkout form.
branding_details object, optional Object containing branding details for the checkout form.
additional_details object, optional Object containing additional details about the checkout form.

Request Arguments - items array

Field Type Description
item.description string, optional Description for the item.
item.image_details object, optional Additional details about the item image.
item.price_details object, optional Additional details about the price.

Request Arguments - items.image_details

Field Type Description
item.image_details.primary_image_url string, optional Primary image URL for the item.
item.image_details.alternative_image_urls array, optional Secondary images URLs for the item.

Request Arguments - items.price_details

Field Type Description
item.price_details.current_price string, optional Details the sale price of the item if different from the regular_price.
item.price_details.currency string, optional 3-letter ISO code designating the currency of the Transfers (e.g. USD).
item.price_details.current_price_type string, optional Add additional details noting if the price is discounted or on sale.
item.price_details.regular_price string, optional The standard price of the item without any adjustments applied (e.g. discounts, taxes, sales).
item.quantity string, optional Set how many units of the item are part of the transaction.

Request Arguments - buyer_details

Field Type Description
identity_id string, optional The Identity ID of the buyer.
first_name string, optional First name of the buyer.
last_name string, optional Last name of the buyer.

Request Arguments - amount_details

Field Type Description
amount_type integer, optional The Identity ID of the buyer.
total_amount integer, optional First name of the buyer.
currency string, optional 3-letter ISO code designating the currency of the Transfers (e.g. USD).
min_amount integer, optional Min amount allowed for VARIABLE amount links.
max_amount integer, optional Max amount allowed for VARIABLE amount links.
amount_breakdown object, optional Breakdown of the total_amount.

Request Arguments - amount_breakdown

Field Type Description
subtotal_amount integer, optional Subtotal amount before tax and other fees.
shipping_amount integer, optional Shipping amount.
estimated_tax_amount integer, optional Estimated tax amount.
min_amount integer, optional Discount amount in cents.
tip_amount integer, optional Tip amount in cents.

Request Arguments - branding

Field Type Description
brand_color string, optional Hex code of branding color (e.g. #F2F2F2).
accent_color string, optional Hex code of the accent color.
logo string, optional URL of the logo for the checkout form.
icon string, optional URL for the icon of the checkout form.

Request Arguments - additional_details

Field Type Description
collect_name boolean, optional Collect name from the checkout form. Defaults to true.
collect_email_address boolean, optional Collect email address from the checkout form.
collect_billing_address boolean, optional Collect billing address from the checkout form. Defaults to false.
collect_shipping_address string, optional Collect shipping address from the checkout form.
success_return_url string, optional URL to redirect the user to after the payment is successful.
unsuccessful_return_url string, optional URL to redirect the user to after the payment is unsuccessful.
expired_session_url string, optional URL to redirect the user to if the checkout form has expired.
terms_of_service_url string, required Terms of service URL for checkout form.
expiration_in_minutes string, optional Expiration for the checkout form in minutes.

States

When a checkout_form is successful, the state of the checkout form will update to COMPLETED.

If a checkout_form is unsuccessful, the buyer is taken back to the checkout form to try submitting payment details again. The checkout_form#state will remain ACTIVE until the form expires or gets deactivated.

Successful Payments

When a buyer successfully submits a checkout_form, the state of the checkout_form updates to COMPLETED.

Terms of Service

attention

You must include a URL to your terms of service when creating a checkout_form.

You must include your terms and services with every checkout_form you create. Your terms and conditions should contain the following information:

General Terms

  • A description of the product or service that you are selling or offering.
  • Any third parties involved in the product you are selling or offering.
  • Reference to which governing law applies to you and your buyers.

Privacy Policy

  • Any data you are storing.
  • Any data you are sharing with third parties.
  • Your cookie policy.

Shipping and Delivery Information

  • Expected delivery and shipping timelines
  • Any restrictions to where you can ship or deliver your goods or services

Refunds and Cancellations

  • Your general refund policies (e.g., 10 days, 30 days, no refunds allowed).
  • Directions on submitting a refund request or canceling a subscription.

Contact Information

You should include general contact information such as:

  • Business name
  • Doing Business as
  • Support Email address
  • Support Phone number