Hosted payment form

Overview

The hosted payment form lets you redirect a customer to a Tilt-hosted page for card entry. Tilt handles the card capture, tokenization, and charge. Your application never touches card data.

Flow

1. Your server creates an order via POST /pos/v1/orders with return_url and cancel_url
2. The response includes a hosted_checkout_url (time-bounded, single-use)
3. You redirect the customer’s browser to hosted_checkout_url
4. Customer enters their card on the Tilt-hosted page
5. On success: browser is redirected to return_url?order_id=…&status=paid
6. On cancel: browser is redirected to cancel_url
7. Your server also receives a payment.approved webhook event

Create an order with a hosted checkout URL

POST /pos/v1/orders

{
  "location_id": "uuid",
  "total_cents": 5000,
  "description": "Fleet service — INV-001",
  "external_reference": "INV-001",
  "return_url": "https://yourapp.example.com/orders/INV-001/success",
  "cancel_url": "https://yourapp.example.com/orders/INV-001/cancel",
  "level3": { ... }
}

Response:

{
  "order_id": "uuid",
  "status": "open",
  "hosted_checkout_url": "https://pos.dev.apps.myfinterra.com/checkout?token=eyJ…",
  "expires_at": "2024-01-15T10:35:00Z"
}

The hosted_checkout_url is valid for 5 minutes and can only be used once.

Brand customisation

The hosted page renders with your partner’s brand configuration (logo, primary colour, button style) set in the admin portal → Brand settings. No additional parameters needed.

return_url parameters

On successful payment the customer is redirected to:

{return_url}?order_id=<uuid>&status=paid

On failed payment they remain on the hosted page to retry.

Security

• The checkout URL contains a short-lived signed token — treat it as a secret and do not log or expose it
• The URL is single-use — a second visit after payment returns 410 Gone
• No card data ever touches your servers