Customize Hosted Checkout

Configure the hosted checkout page to match your brand and business needs.

Branding

The hosted checkout page automatically displays your store branding as configured in the Teya Business Portal. This includes your store name and logo.

Checkout & receipt customisation

The following options can be configured in the Teya Business Portal. These settings apply across all hosted checkout sessions for your store.

Setting	Description	Where it appears	Required
Message on checkout	A custom message shown to the customer before they pay. Use this for order context, instructions, or any terms the customer should see.	Hosted checkout page	No
Message on receipt	A custom message shown after a successful payment. Use this for confirmation notes, next steps, or contact details.	Receipt page	No
Privacy policy URL	A link to your privacy policy. Customers can review how their data is handled before completing payment.	Hosted checkout page	No
Terms & conditions URL	A link to your terms and conditions, displayed alongside the privacy policy link.	Hosted checkout page	No

Session options

These parameters are set per session when calling the Create Session API:

Parameter	Description	Required
`amount`	Payment amount in minor units (e.g. 1000 = 10.00)	Yes
`type`	Transaction type - `SALE`, `PRE_AUTHORISATION`, or `ACCOUNT_VERIFICATION`	Yes
`save_payment_method`	Tokenizes the card so you can charge it again later. See Saving a payment method	No
`success_url`	URL to redirect after successful payment	No
`cancel_url`	URL to redirect if customer cancels	No
`line_items`	Array of order line items with description, quantity, and unit price	No
`merchant_reference`	Your internal order reference for reconciliation	No
`metadata`	Custom key-value pairs stored with the session	No

Amount field structure

The amount object in the session request uses two fields:

amount.valueInteger

Payment amount in the smallest currency unit

amount.currencyString

ISO 4217 currency code

Smallest currency unit

For currencies with two decimal places (EUR, GBP, USD), multiply the amount by 100. For example, €50.00 is 5000 and £9.99 is 999.

Saving a payment method

Consent comes first

Before you store a card, you must obtain and record the customer's agreement to save it and charge it again. That agreement — often called a mandate — defines when, how often, and for how much you can charge the card. It is what makes the later merchant-initiated payments valid.

Set save_payment_method to true when you create the session. The customer enters their card on the Teya-hosted page, so 3D Secure runs there and the card number never touches your systems.

Two fields work together on the session. save_payment_method is what mints the token; type decides what the customer sees on the hosted page:

`type`	`amount.value`	What the hosted page shows
`ACCOUNT_VERIFICATION`	`0`	Saves the card without charging it. The pay button shows no price.
`SALE`	The real amount	Saves the card alongside a real payment.

If you send type: ACCOUNT_VERIFICATION with save_payment_method: false, Teya verifies the card but saves nothing.

{
  "type": "ACCOUNT_VERIFICATION",
  "save_payment_method": true,
  "amount": { "value": 0, "currency": "EUR" },
  "success_url": "https://mywebsite.com/account/cards/saved",
  "cancel_url": "https://mywebsite.com/account/cards"
}

The token arrives on the payment.succeeded.v1 webhook as data.token_response.token_id. Store it alongside data.payment_method.brand and last4 so you can render “Mastercard ••••4065” in your UI.

See Card on File for the consent rules and the wider flow, and Charge a Saved Payment Method for charging the token.

Full API reference

For complete endpoint documentation including all request and response fields, see the Online Payments API Reference.

Session expiry

Checkout sessions expire after 15 minutes. Once expired, the customer will see an error page if they try to access the checkout URL. Create a new session if needed.