Hosted Checkout

Create a checkout session via the Online Payments API and redirect your customer to a Teya-hosted checkout page. The session supports order details, line items, and configurable redirect URLs.

How it works

1 Create checkout session (server)

2 Redirect to session URL

3 Customer completes payment

4 Redirect back + webhook

Full checkout flow with order summary

Supports line items and metadata

Automatic 3DS and error handling

Configurable success/cancel URLs

Before getting started

1. Get your credentials

1 Request a development store with an ecommerce subscription from your Teya contact

2 Log in to the Staging Business Portal with your Teya ID

3 Select your store and go to Integrations

4 Create ecommerce API credentials and configure webhook URLs

You'll receive a Client ID and Client Secret for OAuth authentication

Use client_credentials grant to obtain access tokens

Each store has its own set of credentials

Staging vs Production

Use Staging for development and testing. When ready to go live, repeat the credential setup in Production. Keep separate credentials and token caches for each environment.

2. API URLs

Service	Staging	Production
Online Payments API	`https://api.teya.xyz`	`https://api.teya.com`
OAuth	`https://id.teya.xyz/oauth/v2/oauth-token`	`https://id.teya.com/oauth/v2/oauth-token`
Business Portal	`https://business.teya.xyz`	`https://business.teya.com`

3. Required scopes

Include these as a space-separated string in your OAuth token request:

scope: 'checkout/sessions/create checkout/sessions/id/get refunds/create'

Scope	Description
`checkout/sessions/create`	Create a hosted checkout session
`checkout/sessions/id/get`	Get hosted checkout session by ID
`refunds/create`	Issue a refund for a completed payment

Integrating on behalf of the merchants you serve?

Partners and platforms get credentials through the merchant registration flow instead. See Take payments online for partners.

Example responses

POST - Create a checkout session

{
  "session_id": "14411456-79c8-4d8c-8498-f01907093b83",
  "session_token": "eyJhbGciOiJSUzI1NiJ9...",
  "session_url": "https://checkout.teya.com/session/14411456-79c8-4d8c-8498-f01907093b83",
  "session_status": "ACTIVE"
}

Redirect the customer to session_url. Use session_id to retrieve the session status later.

Info

Use session_url to redirect the customer to the hosted checkout page. Use session_id to check the session status later.
Note on amount.value: Always in the smallest currency unit - for EUR, 5000 = €50.00.

GET - Retrieve a checkout session

{
  "session_id": "14411456-79c8-4d8c-8498-f01907093b83",
  "session_status": "ACTIVE",
  "amount": { "value": 5000, "currency": "EUR" },
  "type": "SALE",
  "payment_status": "NONE",
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cart"
}

Error handling

Status	Meaning	What to do
`401`	Invalid or expired token	Re-authenticate using `client_credentials`
`403`	Missing scope	Ensure `checkout/sessions/create` is in your scope list
`409`	Duplicate idempotency key	Use a unique `Idempotency-Key` header for each request
`422`	Invalid request body	Check `amount.value` is in smallest currency unit

Webhooks - Set up webhooks to receive payment notifications
Customize - Branding, checkout messages, and session options
Testing - Test cards and integration checklist
Troubleshooting - Common issues and best practices
API Reference - Full API endpoint documentation

Try it live - Create a Checkout Session

This will create a real checkout session in the Staging environment. You'll need valid Staging credentials before proceeding.

Staging endpoints shown below

Before going live, swap:
• api.teya.xyz → api.teya.com
• id.teya.xyz → id.teya.com

Node.js example — staging

// 1. Get an access token
const tokenRes = await fetch('https://id.teya.xyz/oauth/v2/oauth-token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'User-Agent': 'Teya-JS-Client/1.0',
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: process.env.TEYA_CLIENT_ID,
    client_secret: process.env.TEYA_CLIENT_SECRET,
    scope: 'checkout/sessions/create',
  }),
});
const { access_token } = await tokenRes.json();

// 2. Create checkout
const apiRes = await fetch('https://api.teya.xyz/v2/checkout/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'User-Agent': 'Teya-JS-Client/1.0',
    Authorization: `Bearer ${access_token}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
      "store_id": "YOUR_STORE_ID",
      "amount": {
        "currency": "EUR",
        "value": 5000
      },
      "type": "SALE",
      "line_items": [
        {
          "description": "Widget Pro",
          "quantity": 2,
          "unit_price": 2500
        }
      ],
      "success_url": "https://yoursite.com/success",
      "cancel_url": "https://yoursite.com/cart"
    }),
});
const data = await apiRes.json();

// Redirect customer
res.redirect(data.session_url);