Create payment links programmatically via the Teya Online Payments API. Ideal for automated billing, e-commerce platforms, and any workflow where you need to generate links at scale.

How it works

Here's the end-to-end flow from creating a link to receiving confirmation:

1 Create payment link via API
2 Share URL with customer
3 Customer pays on hosted page
4 Receive webhook confirmation
No frontend code needed
Works with any platform
Shareable via email, SMS, QR code
Automatic receipt and confirmation

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

ServiceStagingProduction
Online Payments APIhttps://api.teya.xyzhttps://api.teya.com
OAuthhttps://id.teya.xyz/oauth/v2/oauth-tokenhttps://id.teya.com/oauth/v2/oauth-token
Business Portalhttps://business.teya.xyzhttps://business.teya.com

3. Required scopes

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

scope: 'payment-links/create payment-links/id/get payment-links/id/update'

ScopeDescription
payment-links/createCreate a payment link
payment-links/id/getGet payment link by ID
payment-links/id/updateUpdate a payment link
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 payment link

{
  "payment_link_id": "20eb276c-5b6b-4474-a5a1-49bcd6193148",
  "payment_link": "https://checkout.teya.com/pbl/20eb276c-5b6b-4474-a5a1-49bcd6193148"
}

Use payment_link to share with your customer. Use payment_link_id to retrieve or update the link later.

Info
Use payment_url to redirect or send to your customer. Use id to look up or update the link later.
Note on amount.value: Always in the smallest currency unit - for GBP, 2500 = £25.00. 
{
  "payment_link_id": "20eb276c-5b6b-4474-a5a1-49bcd6193148",
  "status": "VALID",
  "amount": { "value": 2500, "currency": "GBP" },
  "merchant_reference": "order-12345",
  "expires_at": "2026-12-31T23:59:59.000Z",
  "line_items": [
    { "description": "Product 1", "quantity": 1, "unit_price": 2500 }
  ],
  "required_customer_fields": ["EMAIL", "PHONE"],
  "metadata": { "order_id": "12345" },
  "customer": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone_number": "+447911123456"
  },
  "billing_address": {
    "city": "London",
    "country": "GB",
    "street_address_line1": "Main Street",
    "zipcode": "SW1A1AA"
  },
  "customer_success_email": "john.doe@example.com",
  "merchant_success_email": "merchant@example.com",
  "post_success_payment": "REDIRECT",
  "success_url": "https://mywebsite.com/checkout/success",
  "cancel_url": "https://mywebsite.com/checkout/cart",
  "supported_card_brands": ["VISA", "MASTERCARD"],
  "supported_payment_methods": ["CARD", "APPLE_PAY"]
}

PATCH - Update expiry

The only updatable field is expires_at. Set it to a future date to extend the link, or a past date to effectively cancel it.

{
  "payment_link_id": "20eb276c-5b6b-4474-a5a1-49bcd6193148",
  "status": "VALID",
  "amount": { "value": 2500, "currency": "GBP" },
  "merchant_reference": "order-12345",
  "expires_at": "2026-07-03T13:37:58.709Z",
  "line_items": [
    { "description": "Product 1", "quantity": 1, "unit_price": 2500 }
  ],
  "required_customer_fields": ["EMAIL", "PHONE"],
  "metadata": { "order_id": "12345" },
  "customer": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone_number": "+447911123456"
  },
  "billing_address": {
    "city": "London",
    "country": "GB",
    "street_address_line1": "Main Street",
    "zipcode": "SW1A1AA"
  },
  "customer_success_email": "john.doe@example.com",
  "merchant_success_email": "merchant@example.com",
  "post_success_payment": "REDIRECT",
  "success_url": "https://mywebsite.com/checkout/success",
  "cancel_url": "https://mywebsite.com/checkout/cart",
  "supported_card_brands": ["VISA", "MASTERCARD"],
  "supported_payment_methods": ["CARD", "APPLE_PAY"]
}

Error handling

StatusMeaningWhat to do
401Invalid or expired tokenRe-authenticate using client_credentials
403Missing scopeEnsure payment-links/create is in your scope list
422Invalid request bodyCheck amount.value is in smallest currency unit (2500 = £25.00)