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.
Before getting started
1. Get merchant credentials
As a partner you take payments on behalf of the merchants you serve. Each merchant's Client ID and Client Secret are delivered to your registrationWebhook when the merchant connects Teya to your platform, along with the store_id and payment_webhook_public_key.
Use client_credentials grant to obtain access tokens
Each merchant store has its own set of credentials
Store credentials securely and never expose them in client-side code
```admonition
icon: fas fa-key
title: A separate Client ID and Client Secret per merchant
content: Unlike POSLink credentials, these aren't shared across your merchant base. Each merchant you serve gets its own Client ID and Client Secret, delivered to your registrationWebhook when they connect - keep each merchant's credentials separate and don't reuse one set across multiple merchants.
```
```admonition
icon: fas fa-user-plus
title: Not registered yet?
content: Set up your partner account and implement the merchant registration flow first. Teya sends each merchant's credentials to your registration webhook.
link: /partners/online-payments/register-merchants
```
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: 'payment-links/create payment-links/id/get payment-links/id/update'
| Scope | Description |
|---|
payment-links/create | Create a payment link |
payment-links/id/get | Get payment link by ID |
payment-links/id/update | Update a payment link |
Example responses
POST - Create a payment link
```json
{
"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.
```admonition
icon: fas fa-info-circle
title: Info
content: 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.
```
GET - Retrieve a payment link
```json
{
"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.
```json
{
"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"]
}
```