Form fields and customization
The Checkout page is shown to the Customer after a payment initiation.
This is the stage where a customer enters their payment data like cards and personal info.
This page covers the fields the customer sees on the rendered form. For the full list of parameters you send in the authentication request — organized by operation type (purchase, debit, credit, transfer) with required and optional columns — see Sale (Authentication session).
Fields and Validation
The list of the fields on the Checkout page depends on the request parameters and the specified payment method.
Your customers will not see the fields if the acquirer does not need the information that is transmitted in them. For example, if an alternative payment method is specified, the card data is not displayed on the Checkout page.
As well, pay attention to the conditional fields such as e-mail or billing address. If the e-mail and billing address (data object) parameters are specified in the request, the Checkout page will not contain them.
Additional fields can also be displayed if a payment method is selected that requests additional data from the Customer.
The Checkout page has the fields validation. In case of the invalid data the error message will be shown and the field will be highlighted.
General fields
Validation rules for the fields rendered by Checkout when they are not supplied in the auth request. Any field you provide in the customer or billing_address object is hidden from the customer.
The Error column shows the literal string returned by the platform on validation failure. Display it to the customer as-is, or map it to your own UI copy.
| Fields | Type | Limitations | Error |
|---|---|---|---|
Card number | Integral | Lun algorithm, length 14-19 numbers | Invalid card |
Expiry Date | Date | 2-2 numbers (in the format mm-yy), after today's date | The expiration date of card is expired and not valid. |
Security code | Integral | Up to 4 characters | Invalid security code |
Name on card | String | Up to 32 characters | The name on card field Must contain at least 2 words: first name and last name. Allowed special characters: hyphens, apostrophes, diacritics |
Country | List | 2-letters code | Country is required. Please enter a valid Country |
State/Region | String List - for USA, Canada, Australia, Japan, India | 2-letter code for US, CA, AU, JP, IN; free string elsewhere | Varies by country |
City | String | 2-40 characters | City is required. Please enter a valid City |
Address line | String | 2-255 characters | Address line is required. Please enter a valid Address line |
Zip code | String | 2-10 characters | Zip code is required. Please enter a valid Zip code |
Phone country code | List | Country calling code chosen from the list, shown with a leading plus sign | Phone country code is required |
Phone number | String | Up to 32 characters | Phone number is required. Please enter a valid Phone number |
Terms & Conditions
When the option is enabled for your account, the payment form shows the checkbox I agree to the Terms & Conditions. It is not ticked by default, and the payment button stays inactive until the customer ticks it. The Terms & Conditions link opens in a new tab: your own terms page if its URL is set, otherwise the general Terms & Conditions page provided by the platform.
With the option enabled, alternative payment methods that use the standard payment form and normally redirect the customer to the provider straight away first show this form with the checkbox and the payment button.
The checkbox is not shown, and the customer pays without it, for:
- Click to Pay. When it is available, card payments go through the Click to Pay form.
- Apple Pay and Google Pay payment buttons.
- Crypto payments.
- Custom payment forms (
form_id) and Hosted Payment Fields. - Payment methods with their own payment form: PayPal, PayNet, Payretailers, SecurePayCard, Fawry, FairPay, Beeline, Zeropay, AWCC, Axxi Transfer, OneCollection, OM Wallet, Interac by email and Interac by SMS.
The checkbox text is translated into English and Bulgarian only. In other Checkout languages it is shown in English.
If no terms URL is set and the platform has no general Terms & Conditions text, the link opens an empty page.
The option and the terms URL are set for the Checkout protocol in Protocol Mapping. Ask your account manager to enable it. Nothing changes in the API: there are no new request parameters, and the customer's acceptance is not returned in responses or callbacks.
iFrame
Embed the Checkout page in an iframe on your domain:
<iframe src="<redirect_url>" height="600" width="300"></iframe>
The browser hosting your iframe must allow third-party cookie storage for the Checkout origin. Without it, the customer is silently logged out during 3DS or redirect flows and the payment session breaks.
Cross-domain requests against Checkout are blocked by CSP.
Customize your page
Two ways to brand the Checkout page: no-code in the admin panel, and custom payment forms via the SDK.
Use the Checkout SDK for branding to create custom payment forms and obtain a form_id for your authentication requests.
No-code branding
In the admin panel, go to Configuration > Branding to customize colors, logo, and buttons. Settings apply globally to all sessions for that merchant. There is no per-session override.
Custom payment forms
If you maintain a branded custom form, send a form_id in the auth request. Configure forms via the SDK Checkout admin module.
{ "form_id": "27106696-656c-...-7e11ae873370" }