OpenAPI Specification
openapi: 3.1.0
info:
title: Teya FX Captures PayByLink API
version: 1.0.0
description: The Teya FX API allows you to fetch the latest exchange rates for currency pairs and perform Dynamic Currency Conversion (DCC). Use this API to verify card eligibility, retrieve real-time exchange rates, and create DCC offers with persisted quotes.
servers:
- url: https://api.teya.com
description: Production Server
- url: https://api.teya.xyz
description: Development Server
tags:
- description: APIs exposed for pay by link customers
name: PayByLink
x-displayName: PayByLink
paths:
/v2/payment-links:
post:
description: 'API to create a new payment link.
<br><strong>Access Token Required scope:</strong> payment-links/create
'
operationId: createPaymentLinkV2
parameters:
- description: 'A unique key to identify the request.
If the request is repeated with the same key, the same response will be returned.
If the request is repeated with a different key or without a key, a new session will be created.
'
in: header
name: Idempotency-Key
required: true
schema:
description: 'A unique key to identify the request.
If the request is repeated with the same key, the same response will be returned.
If the request is repeated with a different key or without a key, a new session will be created.
'
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/pbl_CreatePaymentLinkRequestV2'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/pbl_CreatePaymentLinkResponse'
description: New payment link has been created
'400':
content:
application/json:
example:
code: BAD_REQUEST
description: Bad Request
description: Bad request
'401':
content:
application/json:
example:
code: UNAUTHORISED
description: Unauthorised
description: Lacks valid authentication credentials for the requested resource
'403':
content:
application/json:
example:
code: FORBIDDEN
description: Forbidden
description: The server understands the request but refuses to authorise it
'429':
content:
application/json:
example:
code: TOO_MANY_REQUESTS
description: Too Many Requests
description: Too many requests in a given amount of time
'500':
content:
application/json:
example:
code: INTERNAL_SERVER_ERROR
description: Internal Server Error
description: Internal Server Error
security:
- pbl_oauth_dev: []
- pbl_oauth_prd: []
summary: Creates a new payment link
tags:
- PayByLink
/v1/payment-links/{payment_link_id}:
get:
description: 'API to get a payment link by id.
<br><strong>Access Token Required scope:</strong> payment-links/id/get
'
operationId: getPaymentLink
parameters:
- description: The payment link id
in: path
name: payment_link_id
required: true
schema:
description: A unique identifier for the created payment link
example: 20eb276c-5b6b-4474-a5a1-49bcd6193148
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pbl_GetPaymentLinkResponse'
description: a payment link has been returned
'400':
content:
application/json:
example:
code: BAD_REQUEST
description: Bad Request
description: Bad request
'401':
content:
application/json:
example:
code: UNAUTHORISED
description: Unauthorised
description: Lacks valid authentication credentials for the requested resource
'403':
content:
application/json:
example:
code: FORBIDDEN
description: Forbidden
description: The server understands the request but refuses to authorise it
'404':
content: {}
description: payment link not found
'429':
content:
application/json:
example:
code: TOO_MANY_REQUESTS
description: Too Many Requests
description: Too many requests in a given amount of time
'500':
content:
application/json:
example:
code: INTERNAL_SERVER_ERROR
description: Internal Server Error
description: Internal Server Error
security:
- pbl_oauth_dev: []
- pbl_oauth_prd: []
summary: Gets a payment link by id
tags:
- PayByLink
/v2/payment-links/{payment_link_id}:
patch:
description: 'Updates mutable properties of a payment link.
Currently supports updating expiration timestamp.
<br><strong>Access Token Required scope:</strong> payment-links/id/update
'
operationId: updatePaymentLink
parameters:
- description: The payment link id
in: path
name: payment_link_id
required: true
schema:
description: A unique identifier for the created payment link
example: 20eb276c-5b6b-4474-a5a1-49bcd6193148
format: uuid
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/pbl_UpdatePaymentLinkRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pbl_GetPaymentLinkResponse'
description: Payment link updated successfully
'400':
content:
application/json:
example:
code: BAD_REQUEST
description: Bad Request
description: Bad request
'401':
content:
application/json:
example:
code: UNAUTHORISED
description: Unauthorised
description: Lacks valid authentication credentials for the requested resource
'403':
content:
application/json:
example:
code: FORBIDDEN
description: Forbidden
description: The server understands the request but refuses to authorise it
'404':
content: {}
description: Payment link not found
'429':
content:
application/json:
example:
code: TOO_MANY_REQUESTS
description: Too Many Requests
description: Too many requests in a given amount of time
'500':
content:
application/json:
example:
code: INTERNAL_SERVER_ERROR
description: Internal Server Error
description: Internal Server Error
security:
- pbl_oauth_dev: []
- pbl_oauth_prd: []
summary: Updates an existing payment link
tags:
- PayByLink
components:
schemas:
pbl_Customer:
example:
email: emailaddress@example.com
name: John Doe
phone_number: '+447911123456'
properties:
email:
description: Customer email address
type: string
name:
description: Customer name, used to prefill the hosted checkout form
type: string
phone_number:
description: 'Customer phone number.
An international phone number including the country code, formatted according to the E.164 standard.
'
type: string
title: Customer Information
type: object
pbl_CreatePaymentLinkResponse:
description: The created payment link information
example:
payment_link: https://pbl.teya.com/20eb276c-5b6b-4474-a5a1-49bcd6193148
payment_link_id: 20eb276c-5b6b-4474-a5a1-49bcd6193148
properties:
payment_link:
description: The created payment link
format: url
type: string
payment_link_id:
description: A unique identifier for the created payment link
example: 20eb276c-5b6b-4474-a5a1-49bcd6193148
format: uuid
type: string
required:
- payment_link_id
title: Create Payment Link Response
type: object
pbl_CreatePaymentLinkRequestV2:
description: 'A request to create a payment link.
When used with a user token, the field `store_id` is mandatory.
When used with a terminal token, the field `delivery_info` is mandatory.
'
example:
amount:
currency: USD
value: 100
billing_address:
city: London
country: GB
street_address_line1: Main Street
zipcode: SW1A1AA
cancel_url: https://mywebsite.com/checkout/cart
customer:
email: emailaddress@example.com
name: John Doe
phone_number: '+447911123456'
customer_success_email: john.doe@example.com
delivery_info:
email: emailaddress@example.com
phone_number: '+447700900123'
expires_at: '2024-07-03T13:37:58.709Z'
language: en-GB
line_items:
- description: Product 1
quantity: 1
unit_price: 100
merchant_reference: '12345678'
merchant_success_email: merchant@example.com
metadata:
order_id: '12345'
table_number: '5'
post_success_payment: REDIRECT
required_customer_fields:
- EMAIL
- PHONE
store_id: f47ac10b-58cc-4372-a567-0e02b2c3d479
success_url: https://mywebsite.com/checkout/success
supported_card_brands:
- VISA
- MASTERCARD
supported_payment_methods:
- CARD
- APPLE_PAY
transaction_type: SALE
type: SINGLE_USE
properties:
amount:
$ref: '#/components/schemas/pbl_Amount'
billing_address:
$ref: '#/components/schemas/pbl_AddressDto'
description: Billing address of the customer. Ignored for MULTI_USE payment links.
cancel_url:
description: URL to redirect the customer once the transaction has finished with error or cancellation (must use HTTPS)
type: string
customer:
$ref: '#/components/schemas/pbl_Customer'
description: Customer information. Ignored for MULTI_USE payment links.
customer_success_email:
description: If present, an email is sent to the customer upon successful payment with the receipt.
type: string
delivery_info:
$ref: '#/components/schemas/pbl_DeliveryInfo'
description: Information needed to deliver the link to the merchant customer using email and/or SMS.
expires_at:
description: 'Date when the link will be considered expired in ISO 8601 format.
If not provided, the payment link will not have an expiry date.
'
format: date-time
type: string
language:
description: "The language that will be used to notify the client. It follows IETF BCP 47 and:\n - If provided, it should match any of the supported languages: en-GB, hu-HU, is-IS, cs-CZ, hr-HR, sk-SK, pt-PT, pt-BR, de-DE, es-ES, fr-FR, it-IT, pl-PL\nIf it's different, the request will be rejected with BAD_REQUEST\n - If not provided, the merchant language will be used"
example: en-GB
type: string
line_items:
description: Basket information to be shown in payment page
items:
$ref: '#/components/schemas/pbl_PaymentLinkLineItem'
type: array
merchant_reference:
description: An identifier that can be used to reference the transaction on the merchant's side. Overrides 'source_reference_id
example: '1234567890'
maxLength: 60
type: string
merchant_success_email:
description: If present, an email is sent to the merchant upon successful payment with the receipt.
type: string
metadata:
additionalProperties:
type: string
description: Metadata key-value pairs. Maximum 10 keys allowed. Keys must not exceed 40 characters and values must not exceed 500 characters.
type: object
post_success_payment:
description: Defines the behavior after a successful payment. SHOW_SUCCESS_PAGE displays a success page, REDIRECT redirects to the success_url.
enum:
- SHOW_SUCCESS_PAGE
- REDIRECT
example: SHOW_SUCCESS_PAGE
format: enum
title: Post Success Payment Options
type: string
required_customer_fields:
description: Customer fields that must be collected during checkout
items:
enum:
- SHIPPING_ADDRESS
- PHONE
- EMAIL
type: string
uniqueItems: true
type: array
store_id:
description: The unique identifier of a store
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
format: uuid
title: Store Id
type: string
success_url:
description: URL to redirect the customer once the transaction has successfully finished (must use HTTPS)
type: string
supported_card_brands:
description: Array of supported card brands. If null, defaults to all card brands enabled for the store.
items:
enum:
- AMEX
- MASTERCARD
- VISA
type: string
uniqueItems: true
type: array
supported_payment_methods:
description: Array of supported payment methods. If null, defaults to all payment methods enabled for the store.
items:
enum:
- CARD
- TOKEN
- APPLE_PAY
type: string
uniqueItems: true
type: array
transaction_type:
description: 'Indicates the transaction type. Default is SALE.
Identifies the transaction type. Use SALE for standard payments, PRE_AUTHORISATION to reserve funds for later capture, or ACCOUNT_VERIFICATION to verify and tokenize a card without charging.
'
enum:
- SALE
- PRE_AUTHORISATION
- ACCOUNT_VERIFICATION
example: SALE
format: enum
type: string
type:
description: Indicates the payment link type. Default is SINGLE_USE.
enum:
- SINGLE_USE
example: SINGLE_USE
format: enum
type: string
required:
- amount
title: CreatePaymentLinkRequestV2
type: object
pbl_AddressDto:
description: An address
example:
city: London
country: GB
state: London
street_address_line1: Main Street
street_address_line2: No. 1
street_address_line3: Building 1
zipcode: SW1A1AA
properties:
city:
description: City name
example: London
maxLength: 100
type: string
country:
description: ISO-3166-1 alpha2 country code
example: GB
type: string
state:
description: State or province
example: London
maxLength: 100
type: string
street_address_line1:
description: Street address line 1
example: Main Street
maxLength: 100
type: string
street_address_line2:
description: Street address line 2
example: No. 1
maxLength: 100
type: string
street_address_line3:
description: Street address line 3
example: Building 1
maxLength: 100
type: string
zipcode:
description: Postal/ZIP code
example: SW1A1AA
maxLength: 16
type: string
required:
- country
title: Address
type: object
pbl_Amount:
description: 'The transaction amount in the smallest currency unit according to ISO 4217 format.
For example:
- 100 ISK (Icelandic króna): the amount is 100 (since 1 ISK = 1 subunit).
- 100 EUR (Euro): the amount is 10000 (since 1 EUR = 100 cents).
- 100 USD (US Dollar): the amount is 10000 (since 1 USD = 100 cents).
- 100 KWD (Kuwaiti Dinar): the amount is 100000 (since 1 KWD = 1000 fils).
'
example:
currency: GBP
value: 100
properties:
currency:
description: Currency code (e.g. `USD`, `GBP`, `EUR`) following ISO-4217 format.
enum:
- AED
- AFN
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BDT
- BGN
- BHD
- BIF
- BMD
- BND
- BOB
- BOV
- BRL
- BSD
- BTN
- BWP
- BYN
- BYR
- BZD
- CAD
- CDF
- CHE
- CHF
- CHW
- CLF
- CLP
- CNY
- COP
- COU
- CRC
- CUC
- CUP
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EGP
- ERN
- ETB
- EUR
- FJD
- FKP
- GBP
- GEL
- GHS
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HRK
- HTG
- HUF
- IDR
- ILS
- INR
- IQD
- IRR
- ISK
- JMD
- JOD
- JPY
- KES
- KGS
- KHR
- KMF
- KPW
- KRW
- KWD
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- LYD
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRO
- MRU
- MUR
- MVR
- MWK
- MXN
- MXV
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- OMR
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SBD
- SCR
- SDG
- SEK
- SGD
- SHP
- SLE
- SLL
- SOS
- SRD
- SSP
- STD
- STN
- SVC
- SYP
- SZL
- THB
- TJS
- TMT
- TND
- TOP
- TRY
- TTD
- TWD
- TZS
- UAH
- UGX
- USD
- USN
- UYI
- UYU
- UZS
- VED
- VEF
- VES
- VND
- VUV
- WST
- XAF
- XCD
- XCG
- XOF
- XPF
- YER
- ZAR
- ZMW
- ZWL
format: enum
type: string
value:
description: The transaction amount in the smallest currency unit according to ISO 4217 format.
format: int64
maximum: 9223372036854
type: integer
required:
- currency
- value
title: Transaction Amount
type: object
pbl_PaymentLinkLineItem:
description: Basket information to be shown in payment page
example:
description: Shipping
quantity: 1
unit_price: 100
properties:
description:
description: This a description for a item in the basket
type: string
quantity:
description: The number of items, Must be a positive value
format: int32
type: integer
unit_price:
description: The price of a single item including VAT, Can be negative for discounts
format: int32
type: integer
required:
- description
- quantity
- unit_price
title: PaymentLinkLineItem
type: object
pbl_DeliveryInfo:
example:
email: emailaddress@example.com
phone_number: '+447700900123'
properties:
email:
description: Email address to send the payment link to
type: string
phone_number:
description: 'An international phone number including the country code, formatted according to the E.164 standard.
This is the phone number that we will use to share the payment link via SMS'
type: string
title: DeliveryInfo
type: object
pbl_GetPaymentLinkResponse:
description: The requested payment link data
example:
amount:
currency: USD
value: 100
billing_address:
city: London
country: GB
street_address_line1: Main Street
zipcode: SW1A1AA
cancel_url: https://example.com/cancel
customer:
email: emailaddress@example.com
name: John Doe
phone_number: '+447911123456'
customer_success_email: customer@example.com
expires_at: '2024-07-03T13:37:58.709Z'
line_items:
- description: Product 1
quantity: 1
unit_price: 100
merchant_reference: merchant-reference-id
merchant_success_email: merchant@example.com
metadata:
order_id: '12345'
table_number: '5'
payment_link_id: 20eb276c-5b6b-4474-a5a1-49bcd6193148
post_success_payment: REDIRECT
required_customer_fields:
- EMAIL
- PHONE
status: COMPLETED
success_url: https://example.com/success
supported_card_brands:
- VISA
- MASTERCARD
supported_payment_methods:
- CARD
properties:
amount:
$ref: '#/components/schemas/pbl_Amount'
billing_address:
$ref: '#/components/schemas/pbl_AddressDto'
description: Billing address provided at creation time
cancel_url:
description: URL to redirect to when the customer cancels the payment
type: string
customer:
$ref: '#/components/schemas/pbl_Customer'
description: Customer information provided at creation time
customer_success_email:
description: Email address to send customer success notification to
type: string
expires_at:
description: Date when the link will be considered expired in ISO 8601 format
format: date-time
type: string
line_items:
description: Basket information to be shown in payment page
items:
$ref: '#/components/schemas/pbl_PaymentLinkLineItem'
type: array
merchant_reference:
description: An identifier that can be used to reference the transaction on the merchant's side. Overrides 'source_reference_id
example: '1234567890'
maxLength: 60
type: string
merchant_success_email:
description: Email address to send merchant success notification to
type: string
metadata:
additionalProperties:
type: string
description: Metadata key-value pairs associated with the payment link
type: object
payment_link_id:
description: A unique identifier for the created payment link
example: 20eb276c-5b6b-4474-a5a1-49bcd6193148
format: uuid
type: string
post_success_payment:
description: Action to take after a successful payment
enum:
- SHOW_SUCCESS_PAGE
- REDIRECT
example: SHOW_SUCCESS_PAGE
title: Post Success Payment Options
type: string
required_customer_fields:
description: Customer fields that must be collected during checkout
items:
enum:
- SHIPPING_ADDRESS
- PHONE
- EMAIL
type: string
uniqueItems: true
type: array
status:
description: The status of the payment link
enum:
- VALID
- COMPLETED
- MANUALLY_EXPIRED
- DISABLED
- EXPIRED
type: string
success_url:
description: URL to redirect to after a successful payment
type: string
supported_card_brands:
description: Card brands supported for this payment link
items:
enum:
- AMEX
- MASTERCARD
- VISA
type: string
uniqueItems: true
type: array
supported_payment_methods:
description: Payment methods supported for this payment link
items:
enum:
- CARD
- TOKEN
- APPLE_PAY
type: string
uniqueItems: true
type: array
required:
- amount
- payment_link_id
- status
title: GetPaymentLinkResponse
type: object
pbl_UpdatePaymentLinkRequest:
properties:
expires_at:
description: 'New expiration timestamp in ISO-8601 format.
Expiration can be set up to 5 minutes in the past or any time in the future. Expiry in the past effectively cancels the link.
These links can have their expiration changed if needed in the future again.
Payment link must be in one of the following states to be updated: VALID, EXPIRED, or MANUALLY_EXPIRED.
If not provided in the request, the expiration will not be updated.
If provided as null, the expiration will be cleared.
'
example: '2026-07-03T13:37:58.709Z'
format: date-time
type: string
title: UpdatePaymentLinkRequest
type: object