openapi: 3.1.0
info:
title: Teya APIs for external plugins
version: 1.0.0
description: APIs that external plugins can access
name: Teya
tags:
- description: APIs exposed for session management
name: Hosted Checkout
x-displayName: Hosted Checkout
- description: Transactions
name: Transactions
x-displayName: Transactions
- description: APIs exposed for pay by link customers
name: PayByLink
x-displayName: PayByLink
- name: Receipts
description: Receipts API
x-displayName: Receipts
- name: Captures
description: Operations related to capturing pre-authorised transactions.
x-displayName: Captures
- name: refunds
description: Operations related to refunds.
x-displayName: refunds
- name: Tokens
description: Token management for saved payment methods
x-displayName: Tokens
paths:
/v2/checkout/sessions:
post:
description: |
API to create a hosted checkout session.
Access Token Required scope: checkout/sessions/create
operationId: createSessionV2
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
- description: |
Identifies your integration, for example `YourCompany-Integration/1.0`.
Requests without a `User-Agent` can be blocked by our firewall before they reach the API.
in: header
name: User-Agent
required: true
schema:
example: YourCompany-Integration/1.0
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/checkout_CreateSessionRequest"
required: true
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/checkout_CreateSessionResponse"
description: Session 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
"409":
content: {}
description: Request already processed
"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:
- checkout_oauth_dev: []
- checkout_oauth_prd: []
summary: Creates a new hosted checkout session
tags:
- Hosted Checkout
/v2/checkout/sessions/{session_id}:
get:
description: |
API to return details of a given session.
Access Token Required scope: checkout/sessions/id/get
operationId: getSessionInfoV2
parameters:
- description: The session id
in: path
name: session_id
required: true
schema:
description: This is the id of the session that has been created and will be used to interact across different systems
example: 14411456-79c8-4d8c-8498-f01907093b83
format: uuid
title: Session Id
type: string
- description: |
Identifies your integration, for example `YourCompany-Integration/1.0`.
Requests without a `User-Agent` can be blocked by our firewall before they reach the API.
in: header
name: User-Agent
required: true
schema:
example: YourCompany-Integration/1.0
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/checkout_SessionInfoResponse"
description: Session 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: Session 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:
- checkout_oauth_dev: []
- checkout_oauth_prd: []
summary: Get session details
tags:
- Hosted Checkout
- "'@internal'"
/v2/payment-links:
post:
description: |
API to create a new payment link.
Access Token Required scope: 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
- description: |
Identifies your integration, for example `YourCompany-Integration/1.0`.
Requests without a `User-Agent` can be blocked by our firewall before they reach the API.
in: header
name: User-Agent
required: true
schema:
example: YourCompany-Integration/1.0
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.
Access Token Required scope: 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
- description: |
Identifies your integration, for example `YourCompany-Integration/1.0`.
Requests without a `User-Agent` can be blocked by our firewall before they reach the API.
in: header
name: User-Agent
required: true
schema:
example: YourCompany-Integration/1.0
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.
Access Token Required scope: 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
- description: |
Identifies your integration, for example `YourCompany-Integration/1.0`.
Requests without a `User-Agent` can be blocked by our firewall before they reach the API.
in: header
name: User-Agent
required: true
schema:
example: YourCompany-Integration/1.0
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
/v3/transactions/online:
post:
description: |
API to process an online transaction v3.
Access Token Required scope: transactions/online/create
operationId: processOnlineTransactionV3
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 transaction 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 transaction will be created.
type: string
- description: |
Identifies your integration, for example `YourCompany-Integration/1.0`.
Requests without a `User-Agent` can be blocked by our firewall before they reach the API.
in: header
name: User-Agent
required: true
schema:
example: YourCompany-Integration/1.0
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_ProcessTransactionRequestV2"
required: true
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_ProcessTransactionResponseV2"
description: New transaction has been created and processed by host
"202":
content:
application/json:
schema:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_ProcessTransactionResponseV2"
description: New transaction has been created and still being processed (for example waiting for 3ds challenge to be completed)
"400":
content: {}
description: Bad request due to wrong input
"401":
content: {}
description: Unauthorized request because of missing or invalid authentication token
"403":
content: {}
description: Forbidden request due to lack of permissions
"409":
content: {}
description: Request is already being processed
"422":
content: {}
description: Can not process the request because of an idempotency conflict
"500":
content: {}
description: Internal Server Error
security:
- Ecommerce_Transaction_Payments_-_Public_oauth: []
summary: Process an online transaction v3
tags:
- Transactions
/v2/transactions/online/{authentication_id}:
get:
description: |
API to return details of a given online transaction by its authentication id.
Access Token Required scope: transactions/online/id/get
operationId: getOnlineTransactionV2
parameters:
- description: The authentication id
in: path
name: authentication_id
required: true
schema:
description: The unique identifier for the new transaction by its authentication id
example: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
format: uuid
type: string
- description: |
Identifies your integration, for example `YourCompany-Integration/1.0`.
Requests without a `User-Agent` can be blocked by our firewall before they reach the API.
in: header
name: User-Agent
required: true
schema:
example: YourCompany-Integration/1.0
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_OnlineTransaction"
description: Transaction has been returned
"400":
content: {}
description: Bad request due to wrong input
"401":
content: {}
description: Unauthorized request because of missing or invalid authentication token
"403":
content: {}
description: Forbidden request due to lack of permissions
"404":
content: {}
description: Transaction not found
"500":
content: {}
description: Internal Server Error
security:
- Ecommerce_Transaction_Payments_-_Public_oauth: []
summary: Get an online transaction
tags:
- Transactions
/v1/transactions/{id}/capture:
post:
tags:
- Captures
summary: Capture a pre-authorised transaction
description: |
API to capture a previously pre-authorised transaction.
Usage notes:
- The capture amount must be less than or equal to the original authorisation amount.
- Only one capture is allowed per pre-authorised transaction. Once captured (fully or partially), the transaction cannot be captured again.
Access Token Required scope: captures/create
operationId: captureTransaction
parameters:
- name: id
in: path
description: The transaction ID of the pre-authorisation to capture
required: true
schema:
type: string
description: The transaction ID of the pre-authorisation to capture
minLength: 1
maxLength: 64
example: tr_5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
- name: Idempotency-Key
in: header
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 capture will be created.
required: false
schema:
type: string
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 capture will be created.
- name: User-Agent
in: header
description: |
Identifies your integration, for example `YourCompany-Integration/1.0`.
Requests without a `User-Agent` can be blocked by our firewall before they reach the API.
required: true
schema:
type: string
example: YourCompany-Integration/1.0
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CaptureRequest"
required: true
responses:
"201":
description: Capture processed
content:
application/json:
schema:
$ref: "#/components/schemas/CaptureResponse"
"202":
description: Capture processing
content:
application/json:
schema:
$ref: "#/components/schemas/CaptureResponse"
"400":
description: Bad Request
content: {}
"401":
description: Unauthorised
content: {}
"403":
description: Forbidden
content: {}
"404":
description: Transaction not found
content: {}
"409":
description: Conflict
content: {}
"500":
description: Internal Server Error
content: {}
security:
- Ecommerce_Transaction_Payments_-_Public_oauth: []
/v3/refunds:
post:
tags:
- Transactions
summary: Process a refund of a transaction
description: |
API to process the refund of a previous transaction.
Access Token Required scope: refunds/create
operationId: refunds
parameters:
- name: Idempotency-Key
in: header
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 refund will be created.
required: false
schema:
type: string
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 refund will be created.
maxLength: 64
minLength: 1
- name: User-Agent
in: header
description: |
Identifies your integration, for example `YourCompany-Integration/1.0`.
Requests without a `User-Agent` can be blocked by our firewall before they reach the API.
required: true
schema:
type: string
example: YourCompany-Integration/1.0
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/RefundRequest"
required: true
responses:
"201":
description: Refund processed
content:
application/json:
schema:
$ref: "#/components/schemas/RefundResponse"
"202":
description: Refund processing
"400":
description: Bad Request
content: {}
"401":
description: Unauthorised
content: {}
"403":
description: Forbidden
content: {}
"404":
description: Not Found
content: {}
"409":
description: Conflict
content: {}
"460":
description: Challenge Required
content: {}
"500":
description: Internal Server Error
content: {}
"503":
description: Service Unavailable
content: {}
"523":
description: Origin Unavailable
content: {}
security:
- Payments_Refunds_Wrapper_API_oauth_dev: []
- Payments_Refunds_Wrapper_API_oauth_prd: []
/v1/transactions/{transaction_id}/receipts:
post:
tags:
- Transactions
summary: Create a digital receipt for a transaction
description: |
API to allow merchants to request the generation of a digital receipt for a transaction.
Access Token Required scope: transactions/id/receipts/create
operationId: createReceipt
parameters:
- name: transaction_id
in: path
description: Transaction id whose receipt we want to generate
required: true
schema:
type: string
description: Transaction id whose receipt we want to generate
example: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
example: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
- name: User-Agent
in: header
description: |
Identifies your integration, for example `YourCompany-Integration/1.0`.
Requests without a `User-Agent` can be blocked by our firewall before they reach the API.
required: true
schema:
type: string
example: YourCompany-Integration/1.0
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Teya_Digital_Receipts_Service_CreateReceiptRequest"
required: true
responses:
"202":
description: Receipt successfully enqueued for generation
content:
application/json:
schema:
$ref: "#/components/schemas/Teya_Digital_Receipts_Service_CreateReceiptResponse"
"400":
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/Teya_Digital_Receipts_Service_Error"
example:
code: BAD_REQUEST
description: Bad Request
"401":
description: Lacks valid authentication credentials for the requested resource
content:
application/json:
schema:
$ref: "#/components/schemas/Teya_Digital_Receipts_Service_Error"
example:
code: UNAUTHORISED
description: Unauthorised
"403":
description: The server understands the request but refuses to authorise it
content:
application/json:
schema:
$ref: "#/components/schemas/Teya_Digital_Receipts_Service_Error"
example:
code: FORBIDDEN
description: Forbidden
"429":
description: Too many requests in a given amount of time
content:
application/json:
schema:
$ref: "#/components/schemas/Teya_Digital_Receipts_Service_Error"
example:
code: TOO_MANY_REQUESTS
description: Too Many Requests
"500":
description: Internal Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/Teya_Digital_Receipts_Service_Error"
example:
code: INTERNAL_SERVER_ERROR
description: Internal Server Error
/v1/tokens/{token_id}:
delete:
tags:
- Tokens
summary: Delete a saved payment token
description: |
Remove a previously saved payment method token. Once deleted, the token can no longer be used for transactions.
Access Token Required scope: token/delete
operationId: deleteToken
parameters:
- name: token_id
in: path
description: The unique identifier of the token to delete
required: true
schema:
type: string
format: uuid
example: "5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b"
- name: store_id
in: query
description: The store that owns the token
required: true
schema:
type: string
format: uuid
example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
- name: User-Agent
in: header
description: |
Identifies your integration, for example `YourCompany-Integration/1.0`.
Requests without a `User-Agent` can be blocked by our firewall before they reach the API.
required: true
schema:
type: string
example: YourCompany-Integration/1.0
responses:
"204":
description: Token successfully deleted
"400":
description: Bad request
"401":
description: Unauthorized
"404":
description: Token not found
"500":
description: Internal Server Error
components:
schemas:
checkout_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
checkout_BackendBusinessData:
description: The business information
example:
active: true
address:
city: New York
country: US
state: NY
street_address_line1: 123 Main St
street_address_line2: Suite 100
street_address_line3: Building 1
zipcode: "10001"
id: 123e4567-e89b-12d3-a456-426614174000
name: My Business
notification_email: example@email.com
properties:
active:
type: boolean
address:
$ref: "#/components/schemas/checkout_BusinessAddress"
id:
description: The unique identifier of a business (associated store entity)
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
format: uuid
title: Business Id
type: string
name:
description: The name of a business
example: Teya Global
title: Business Name
type: string
notification_email:
example: example@email.com
title: Email Address
type: string
required:
- active
- address
- id
- name
title: Business Data
type: object
checkout_BillingAddress:
description: Customer's Billing Address
example:
city: London
country: GB
state: London
street_address_line1: Main Street
street_address_line2: No. 1
street_address_line3: Building 1
zipcode: "10001"
properties:
city:
description: The city where the business is located
example: New York
title: City
type: string
country:
description: The country where the business is located (ISO-3166-1 alpha2)
example: ES
title: Country
type: string
state:
description: The state where the business is located
example: NY
title: State
type: string
street_address_line1:
description: The street address of a business
example: 123 Main St
title: Street Address Line
type: string
street_address_line2:
description: The street address of a business
example: 123 Main St
title: Street Address Line
type: string
street_address_line3:
description: The street address of a business
example: 123 Main St
title: Street Address Line
type: string
zipcode:
description: The zipcode where the business is located
example: "10001"
title: Zipcode
type: string
required:
- country
title: Billing Address
type: object
checkout_BusinessAddress:
description: The address of a business
example:
city: New York
country: US
state: NY
street_address_line1: Main Street
street_address_line2: No. 1
street_address_line3: Building 1
zipcode: "10001"
properties:
city:
description: The city where the business is located
example: New York
title: City
type: string
country:
description: The country where the business is located (ISO-3166-1 alpha2)
example: ES
title: Country
type: string
state:
description: The state where the business is located
example: NY
title: State
type: string
street_address_line1:
description: The street address of a business
example: 123 Main St
title: Street Address Line
type: string
street_address_line2:
description: The street address of a business
example: 123 Main St
title: Street Address Line
type: string
street_address_line3:
description: The street address of a business
example: 123 Main St
title: Street Address Line
type: string
zipcode:
description: The zipcode where the business is located
example: "10001"
title: Zipcode
type: string
required:
- country
title: Business Address
type: object
checkout_CreateSessionRequest:
description: Creates a Hosted Checkout session that will be used to process an Ecommerce transaction
example:
amount:
currency: USD
value: 100
billing_address:
city: London
country: GB
state: London
street_address_line1: Main Street
street_address_line2: No. 1
street_address_line3: Building 1
zipcode: "10001"
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
failure_url: https://mywebsite.com/checkout/failure
language: en-GB
line_items:
- description: Product 1
quantity: 1
unit_price: 100
- description: Product 2
quantity: 2
unit_price: 50
merchant_reference: "1234567890"
merchant_success_email: customer@mywebsite.com
metadata:
campaign: summer_sale
order_id: "12345"
post_success_payment: SHOW_SUCCESS_PAGE
required_customer_fields:
- SHIPPING_ADDRESS
- EMAIL
save_payment_method: true
store_id: 123e4567-e89b-12d3-a456-426614174000
success_url: https://mywebsite.com/checkout/success
type: SALE
properties:
amount:
$ref: "#/components/schemas/checkout_Amount"
billing_address:
$ref: "#/components/schemas/checkout_BillingAddress"
description: Billing address of the customer
cancel_url:
description: URL to bring back the customer to the cart. If included in the call we will render the “Back” button in the HostedCheckout UI
type: string
customer:
$ref: "#/components/schemas/checkout_Customer"
description: Customer information
customer_success_email:
description: If present, an e-mail is sent to the merchant customer upon successful payment with the receipt.
type: string
failure_url:
description: URL to redirect the customer once the transaction has finished with error
type: string
language:
description: |-
The language to be used in the Hosted Checkout session in case the Accept-Language from the Customer browser does not exist or doesn’t match any of the allowed languages. It follows IETF BCP 47 and:
- 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
If it's different, the request will be rejected with BAD_REQUEST
- If not provided, en-GB will be used when the Accept-Language from the Customer browser doesn't match
example: en-GB
type: string
line_items:
description: Basket information to be shown in payment page
items:
$ref: "#/components/schemas/checkout_SessionLineItem"
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 e-mail is sent to the merchant upon successful payment with the receipt.
type: string
metadata:
additionalProperties:
type: string
description: Metadata key-value pairs for the session. Maximum 10 keys allowed. Keys must not exceed 40 characters and values must not exceed 500 characters.
type: object
post_success_payment:
description: |
Where the customer browser will be sent after a successful transaction.
Possible values:
SHOW_SUCCESS_PAGE (Display the HostedCheckout payment completed page with a button to redirect to the success_url),
REDIRECT (Redirect the customer browser directly to the success_url).
Note: For transactions with Dynamic currency conversion (DCC), we will not redirect and will show success page if no
customer_success_email is sent. Because we are required to show the rates to the customer.
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
type: array
save_payment_method:
description: |
When set to true, the customer's payment method is tokenized during the session and a token_id is returned
in the payment.succeeded.v1 webhook and on the resulting transaction, for use in future payments.
Combine with type ACCOUNT_VERIFICATION and a zero amount to save a card without charging the customer,
or with type SALE to save it alongside a real payment. Requires tokenization to be enabled for the store.
example: true
type: boolean
store_id:
description: Store ID for the session. If not provided, it will be attempted to retrieve the store_id from the association with the client_id.
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
type: string
type:
description: |
Indicates the transaction type.
Use SALE for standard payments, PRE_AUTHORISATION to reserve funds for later capture,
or ACCOUNT_VERIFICATION to verify a card without charging it. ACCOUNT_VERIFICATION requires
an amount value of 0 and must be enabled for the store; combine it with save_payment_method
to save the card for future payments.
enum:
- ACCOUNT_VERIFICATION
- PRE_AUTHORISATION
- SALE
format: enum
type: string
required:
- amount
- type
title: CreateSessionRequest
type: object
checkout_CreateSessionResponse:
description: Result of the creation of a Hosted Checkout session that will be used to process an Ecommerce transaction
example:
session_id: 14411456-79c8-4d8c-8498-f01907093b83
session_url: https://checkout.teya.com/pay/14411456-79c8-4d8c-8498-f01907093b83
properties:
session_id:
description: This is the id of the session that has been created and will be used to interact across different systems
example: 14411456-79c8-4d8c-8498-f01907093b83
format: uuid
title: Session Id
type: string
session_url:
description: The hosted checkout session url that the merchant can use to redirect the customer once the session has been created
example: https://checkout.teya.com/pay/_0XBPWQQ_7c35b74c-4ce3-4d33-8928-c2aa62970ce2
format: url
type: string
required:
- session_id
- session_url
title: CreateSessionResponse
type: object
checkout_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
checkout_DccOfferInfo:
description: Dynamic Currency Conversion offer info for a session.
properties:
cardholder_amount:
$ref: "#/components/schemas/checkout_Amount"
ecb_markup:
description: Markup of the offered exchange rate (i.e. amount added) over the latest ECB exchange rate for a currency pair (decimal format, with 6 decimal places). Only provided when both currencies are EEA currencies.
example: "0.005000"
type: string
exchange_rate:
description: Latest exchange rate for a currency pair (decimal format, with 6 decimal places)
example: "1.234567"
type: string
markup:
description: Markup of the offered exchange rate (i.e. amount added) over the latest exchange rate for a currency pair (decimal format)
example: "0.010000"
type: string
required:
- cardholder_amount
- exchange_rate
- markup
title: DccOfferInfo
type: object
checkout_SessionInfoResponse:
description: Returns the Hosted Checkout session information that will be used to process an Ecommerce transaction
example:
amount:
currency: USD
value: 100
billing_address:
city: London
country: GB
state: London
street_address_line1: Main Street
street_address_line2: No. 1
street_address_line3: Building 1
zipcode: "10001"
business_data:
active: true
address:
city: New York
country: US
state: NY
street_address_line1: 123 Main St
street_address_line2: Suite 100
street_address_line3: Building 1
zipcode: "10001"
id: 123e4567-e89b-12d3-a456-426614174000
name: My Business
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
failure_url: https://mywebsite.com/checkout/failure
language: en-GB
line_items:
- description: Product 1
quantity: 1
unit_price: 50
- description: Product 2
quantity: 2
unit_price: 25
merchant_reference: "1234567890"
merchant_success_email: customer@mywebsite.com
metadata:
campaign: summer_sale
order_id: "12345"
payment_link_id: 01960f72-872c-7894-a7da-98b0eaaf6588
payment_link_type: SINGLE_USE
payment_status: NONE
post_success_payment: SHOW_SUCCESS_PAGE
required_customer_fields:
- SHIPPING_ADDRESS
- EMAIL
- PHONE
session_id: 14411456-79c8-4d8c-8498-f01907093b83
session_status: ACTIVE
source_reference_id: "1234567890"
success_url: https://mywebsite.com/checkout/success
transaction_id: tr_72302a4d-b2f9-4663-93f8-d9260e5370c8
type: SALE
logo_url: https://example.cloudfront.net/stores/123/logo.png
checkout_custom_note: Thank you for shopping with us!
privacy_policy_url: https://mywebsite.com/privacy
terms_url: https://mywebsite.com/terms
properties:
amount:
$ref: "#/components/schemas/checkout_Amount"
billing_address:
$ref: "#/components/schemas/checkout_BillingAddress"
description: Billing address of the customer
example:
city: London
country: GB
state: London
street_address_line1: Main Street
street_address_line2: No. 1
street_address_line3: Building 1
zipcode: "10001"
business_data:
$ref: "#/components/schemas/checkout_BackendBusinessData"
cancel_url:
description: URL to bring back the customer to the cart. If included in the call we will render the “Back” button in the HostedCheckout UI
type: string
customer:
$ref: "#/components/schemas/checkout_Customer"
customer_success_email:
description: If present, an e-mail is sent to the merchant customer upon successful payment with the receipt.
type: string
dcc:
$ref: "#/components/schemas/checkout_DccOfferInfo"
description: Dynamic Currency Conversion offer info for the session.
enabled_card_brands:
description: List of enabled card brands for the session.
example:
- VISA
- MASTERCARD
- AMEX
items:
enum:
- AMEX
- CALLIO
- CARDCO
- UNION_PAY
- DINERS
- DISCOVER
- DOXX
- GENERALI
- JCB
- KH
- MAESTRO
- MASTERCARD
- OTHER
- OTP
- PATIKA
- PREMIUM
- SODEXO
- UP
- VISA
- VITAMIN
type: string
uniqueItems: true
type: array
uniqueItems: true
failure_url:
description: URL to redirect the customer once the transaction has finished with error
type: string
language:
description: The language to be used in the Hosted Checkout session. IETF BCP 47. If not provided we will use for rendering in HC the Accept-Language request header.
example: en-GB
type: string
line_items:
description: Basket information to be shown in the payment screen
example:
- description: Product 1
quantity: 1
unit_price: 100
- description: Product 2
quantity: 2
unit_price: 50
items:
$ref: "#/components/schemas/checkout_SessionLineItem"
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 e-mail is sent to the merchant upon successful payment with the receipt.
type: string
metadata:
additionalProperties:
type: string
description: Metadata key-value pairs for the session. Maximum 10 keys allowed. Keys must not exceed 40 characters and values must not exceed 500 characters.
type: object
payment_link_id:
description: A unique identifier for the created payment link
example: 20eb276c-5b6b-4474-a5a1-49bcd6193148
format: uuid
type: string
payment_link_type:
description: Type of the payment link used to create the session
enum:
- SINGLE_USE
format: enum
type: string
payment_status:
description: Status of the payment, only present when the session status is COMPLETED.
enum:
- NONE
- SUCCESS
- FAILED
example: SUCCESS
format: enum
title: |
Status of the payment.
NONE: No payment has been processed
SUCCESS: Payment has been successful
FAILED: Payment has failed
type: string
post_success_payment:
description: |
Where the customer browser will be sent after a successful transaction.
Possible values:
SHOW_SUCCESS_PAGE (Display the HostedCheckout payment completed page with a button to redirect to the success_url),
REDIRECT (Redirect the customer browser directly to the success_url).
Note: For transactions with Dynamic currency conversion (DCC), we will not redirect and will show success page if no
customer_success_email is sent. Because we are required to show the rates to the customer.
enum:
- SHOW_SUCCESS_PAGE
- REDIRECT
example: SHOW_SUCCESS_PAGE
format: enum
title: Post Success Payment Options
type: string
session_id:
description: This is the id of the session that has been created and will be used to interact across different systems
example: 14411456-79c8-4d8c-8498-f01907093b83
format: uuid
title: Session Id
type: string
session_status:
description: Indicates whether the session is still available for use. New payments can only happen when the status is ACTIVE
enum:
- ACTIVE
- PROCESSING
- COMPLETED
- EXPIRED
example: ACTIVE
format: enum
title: |
Status of the session
ACTIVE: Session has been created but the payment processing has not started
PROCESSING: A payment has started but has not been completed
COMPLETED: Session has been finished because a payment has succeeded or failed
EXPIRED: Session has expired
type: string
required_customer_fields:
description: Customer fields that must be collected during checkout
items:
enum:
- SHIPPING_ADDRESS
- PHONE
- EMAIL
type: string
type: array
success_url:
description: URL to redirect the customer once the transaction has successfully finished
type: string
logo_url:
description: Public URL of the merchant's logo to display on the checkout page. Configured in the Teya Business Portal.
example: https://example.cloudfront.net/stores/123/logo.png
type: string
checkout_custom_note:
description: Custom note to display on the checkout page. Maximum 1000 characters. Configured in the Teya Business Portal.
example: Thank you for shopping with us!
maxLength: 1000
type: string
privacy_policy_url:
description: HTTPS URL linking to the merchant's privacy policy. Displayed on the checkout page. Configured in the Teya Business Portal.
example: https://mywebsite.com/privacy
type: string
terms_url:
description: HTTPS URL linking to the merchant's terms and conditions. Displayed on the checkout page. Configured in the Teya Business Portal.
example: https://mywebsite.com/terms
type: string
transaction_id:
description: The unique identifier for the new transaction
example: tr_72302a4d-b2f9-4663-93f8-d9260e5370c8
type: string
type:
description: |
Indicates the transaction type.
Use SALE for standard payments, PRE_AUTHORISATION to reserve funds for later capture,
or ACCOUNT_VERIFICATION to verify a card without charging it.
enum:
- ACCOUNT_VERIFICATION
- PRE_AUTHORISATION
- SALE
format: enum
type: string
required:
- amount
- business_data
- payment_status
- session_id
- session_status
- type
title: SessionInfoResponse
type: object
checkout_SessionLineItem:
description: Basket information to be shown in the payment screen
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 to 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: SessionLineItem
type: object
Ecommerce_Transaction_Payments_-_Public_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
Ecommerce_Transaction_Payments_-_Public_ApplePayAuthenticationData:
description: Represents the decrypted data from an Apple Pay payment token, including card details, transaction information, and merchant metadata.
example:
application_primary_account_number: "4895370012345678"
eci_code: "05"
expiry_month: "10"
expiry_year: "2025"
last_4_card_digits: "5678"
online_payment_cryptogram: SGVsbG8sIHdvcmxkIQ==
properties:
application_primary_account_number:
description: Device-specific account number of the card that funds this transaction
type: string
eci_code:
description: ECI code for the transaction
type: string
expiry_month:
description: Card expiration month
type: string
expiry_year:
description: Card expiration year
type: string
last_4_card_digits:
description: Last four digits of the card behind the Apple Pay token. Use it to show the customer which card is saved.
example: "5678"
maxLength: 4
minLength: 4
pattern: "^[0-9]{4}$"
type: string
online_payment_cryptogram:
description: Apple pay online payment cryptogram
type: string
required:
- application_primary_account_number
- expiry_month
- expiry_year
- online_payment_cryptogram
title: ApplePayAuthenticationData
type: object
Ecommerce_Transaction_Payments_-_Public_Address:
description: Customer's address
example:
name: John Doe
city: London
country: GB
state: London
street_address_line1: Main Street
street_address_line2: No. 1
street_address_line3: Building 1
zipcode: "10001"
properties:
name:
description: Name associated with the address
example: John Doe
type: string
city:
description: City name
example: London
title: City
type: string
country:
description: ISO 3166-1 alpha-2 country code
example: GB
title: Country
type: string
state:
description: State or region
example: Greater London
title: State
type: string
street_address_line1:
description: Primary street address
example: 123 Main St
title: Street Address Line
type: string
street_address_line2:
description: Secondary street address (apt, suite, etc.)
example: Flat 4
title: Street Address Line
type: string
street_address_line3:
description: Additional address line
example: Building A
title: Street Address Line
type: string
zipcode:
description: Postal/ZIP code
example: SW1A 1AA
title: Zipcode
type: string
required:
- country
title: Address
type: object
Ecommerce_Transaction_Payments_-_Public_CustomerContact:
description: Customer contact details
example:
phone_number: "+34610123456"
email: john.doe@example.com
properties:
phone_number:
description: Customer's phone number
example: "+34610123456"
type: string
email:
description: Customer's email address
example: john.doe@example.com
type: string
title: CustomerContact
type: object
Ecommerce_Transaction_Payments_-_Public_BrowserData:
description: Browser information transmitted during the authentication request process to enhance verification accuracy.
example:
accept_language: en-GB,en;q=0.9,pt;q=0.8,pt-PT;q=0.7,nl;q=0.6
ip_address: 192.16.1.1
screen_height: 1080
screen_width: 1920
user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.1234.0 Safari/537.36
properties:
accept_language:
description: User preferred language from the browser
type: string
ip_address:
description: IP address of the browser
type: string
screen_height:
description: Screen height of the browser
format: int32
type: integer
screen_width:
description: Screen width of the browser
format: int32
type: integer
user_agent:
description: User agent of the browser
type: string
required:
- ip_address
- screen_height
- screen_width
title: BrowserData
type: object
Ecommerce_Transaction_Payments_-_Public_Card:
example:
cvc: "123"
expiry_month: "02"
expiry_year: "2030"
number: "4111111111111111"
properties:
cvc:
description: 3 or 4 digit card verification code for the card
type: string
expiry_month:
description: 2-digit month of expiration for the card
type: string
expiry_year:
description: 4-digit year of expiration for the card
type: string
number:
description: Primary Account Number (PAN) of a card. Sent without spaces or dashes
type: string
required:
- cvc
- expiry_month
- expiry_year
- number
title: Card
type: object
Ecommerce_Transaction_Payments_-_Public_Cardholder:
description: Information about the cardholder
example:
email: john.doe@example.com
name: John Doe
phone_number: "+34610123456"
properties:
email:
description: Email address of the cardholder
example: john.doe@example.com
type: string
name:
description: Full name of the cardholder
example: John Doe
title: Cardholder Name
type: string
phone_number:
description: Phone number of the cardholder
example: "+34610123456"
type: string
required:
- name
title: Cardholder
type: object
Ecommerce_Transaction_Payments_-_Public_IssuerResult:
description: Result data for the transaction according to issuer's response
example:
approval_code: "123456"
response_code: "00"
properties:
approval_code:
description: Identifier of the authorisation returned by the issuer. When the transaction is not authorised, this field is empty
type: string
response_code:
description: Response code returned by the issuer, indicating the result of the operation as per ISO-8583 (https://en.wikipedia.org/wiki/ISO_8583#Ver_1987)
type: string
title: IssuerResult
type: object
Ecommerce_Transaction_Payments_-_Public_LineItem:
example:
description: Shipping
quantity: 1
unit_price: 100
properties:
description:
description: This is a description for an 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: LineItem
type: object
Ecommerce_Transaction_Payments_-_Public_OnlineTransaction:
description: The response for a transaction request
example:
authentication_id: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
created_at: "2022-03-01T15:29:59Z"
issuer_result:
approval_code: "123456"
response_code: "00"
status: SUCCESS
transaction_id: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
updated_at: "2022-03-01T15:35:00Z"
properties:
authentication_id:
description: The unique identifier for the authentication
example: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
format: uuid
type: string
created_at:
description: The datetime that the transaction was created (ISO 8601 format)
format: date-time
type: string
issuer_result:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_IssuerResult"
status:
description: The status of the transaction
enum:
- SUCCESS
- FAILURE
- PENDING
example: SUCCESS
type: string
status_reason:
description: Detailed reasons for the transaction failure status. This is provided when the transaction response status is FAILURE and is null when the payment succeeds or is pending.
enum:
- ACCOUNT_INVALID
- BLOCKED_CARD
- BLOCKED_CROSS_BORDER_TRANSACTION
- AMOUNT_TOO_SMALL
- CANNOT_VALIDATE_AUTHENTICATION
- CARD_COUNT_EXCEEDED
- CARD_DECLINED
- CARD_EXPIRED
- CARD_LIMIT_EXCEEDED
- CARD_NOT_ACTIVE
- DISABLED_ACCOUNT
- DO_NOT_HONOR
- ECOM_NEGATIVE_CARD_AUTHENTICATION_VERIFICATION
- EXCEEDS_AMOUNT_LIMIT
- FORMAT_ERROR
- INCORRECT_CARD_AUTHENTICATION
- INSUFFICIENT_FUNDS
- INVALID_CARD_NUMBER
- INVALID_TRANSACTION
- ISSUER_DECLINED
- LOST_OR_STOLEN
- MERCHANT_CONFIGURATION
- NEGATIVE_BALANCE
- PIN_LIMIT_EXCEEDED
- PROCESSOR_UNAVAILABLE
- RESTRICTED_CARD
- SCA_PIN_REQUIRED
- SCA_REQUIRED
- SUSPECTED_FRAUD
- TEMPORARY_ISSUE_RETRY
- TIMEOUT
- TRANSACTION_NOT_ALLOWED
- UNABLE_TO_ROUTE_TRANSACTION
- UNSUPPORTED_ISSUER
- FEATURE_NOT_ACTIVATED_MANUAL_ENTRY
- FEATURE_NOT_ACTIVATED_PAY_BY_LINK
- FEATURE_NOT_ACTIVATED_ECOMMERCE
- FEATURE_NOT_ACTIVATED_UNREFERENCED_REFUNDS
- OTHER
format: enum
type: string
token_response:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_TokenCreationResponse"
description: The details of the created token
transaction_id:
description: The unique identifier for the new transaction
example: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
format: uuid
type: string
updated_at:
description: The datetime that the transaction was updated (ISO 8601 format)
format: date-time
type: string
required:
- authentication_id
- created_at
- status
- transaction_id
- updated_at
title: OnlineTransaction
type: object
Ecommerce_Transaction_Payments_-_Public_PaymentMethod:
example:
card:
cvc: "123"
expiry_month: "02"
expiry_year: "2030"
number: "4111111111111111"
type: CARD
properties:
apple_pay_authentication_data:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_ApplePayAuthenticationData"
description: Apple Pay Authentication Data
card:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_Card"
description: Card payment method
legacy_token:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_LegacyToken"
description: Legacy platform token being migrated
token:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_Token"
description: Token for saved payment method
type:
description: Payment method type
enum:
- CARD
- TOKEN
- APPLE_PAY
- LEGACY_TOKEN
format: enum
type: string
required:
- type
title: PaymentMethod
type: object
Ecommerce_Transaction_Payments_-_Public_Token:
description: A saved payment method token for recurring or card-on-file transactions
example:
token_id: "5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b"
recurring_payment_type: CARD_ON_FILE
properties:
token_id:
description: The unique identifier of the saved token
example: "5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b"
format: uuid
type: string
recurring_payment_type:
description: The type of recurring payment
enum:
- CARD_ON_FILE
- RECURRING
- INSTALLMENT
format: enum
type: string
token_type:
description: |
Type of the stored token. `CARD_TOKEN` for tokens created from card details, `WALLET_TOKEN` for tokens created from Apple Pay. Defaults to `CARD_TOKEN` when omitted.
Send back the `token_type` returned in `token_response` when the token was created. A wallet token charged without it is looked up as a card token and fails with `404`.
Wallet tokens can only be charged with `initiator: MERCHANT`.
enum:
- CARD_TOKEN
- WALLET_TOKEN
format: enum
nullable: true
type: string
required:
- token_id
- recurring_payment_type
title: Token
type: object
Ecommerce_Transaction_Payments_-_Public_LegacyToken:
description: |
A token issued by the legacy platform, used with payment method `LEGACY_TOKEN` while migrating stored cards.
The first charge converts it to a Teya token, returned in `token_response.token_id`; send that `token_id` as payment method `TOKEN` for every later charge.
Charging the same legacy token again returns the same Teya token. Enabled per store by Teya once the stored cards import is complete.
See [Migrating stored cards & recurring payments](/online-payments/migration/stored-cards).
example:
token_id: "tm_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"
recurring_payment_type: CARD_ON_FILE
properties:
token_id:
description: The legacy token exactly as stored. Either an RPG multi-use token (`tm_` prefix, e.g. `tm_abc123`) or a virtual card PAN (16 digits starting with `991001`, e.g. `9910012837465190`). At most 64 characters.
example: "tm_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"
maxLength: 64
pattern: "^(tm_[a-zA-Z0-9_-]+|991001[0-9]{10})$"
type: string
recurring_payment_type:
description: The type of recurring payment
enum:
- CARD_ON_FILE
- RECURRING
- INSTALLMENT
format: enum
type: string
required:
- token_id
- recurring_payment_type
title: LegacyToken
type: object
Ecommerce_Transaction_Payments_-_Public_ProcessTransactionRequestV2:
description: A request to process a transaction
example:
amount:
currency: GBP
value: 100
browser_data:
accept_language: en-GB,en;q=0.9,pt;q=0.8,pt-PT;q=0.7,nl;q=0.6
ip_address: 127.0.0.1
screen_height: 1080
screen_width: 1920
user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
billing_address:
name: John Doe
country: GB
city: London
state: Greater London
street_address_line1: 123 High Street
street_address_line2: Flat 4
zipcode: SW1A 1AA
cardholder:
name: John Doe
customer_contact:
phone_number: "+447123456789"
email: john.doe@example.com
initiator: CUSTOMER
line_items:
- description: Product Name
id: 550e8400-e29b-41d4-a716-446655440000
quantity: 2
unit_price: 1000
merchant_reference_id: "1234567890"
payment_method:
card:
cvc: "123"
expiry_month: "02"
expiry_year: "2030"
number: "4111111111111111"
type: CARD
redirect_url: https://mywebsite.com/processing
shipping_address:
name: Jane Doe
country: GB
city: Manchester
state: Greater Manchester
street_address_line1: 456 Oak Avenue
zipcode: M1 1AA
store_id: 7a3f2c21-5d6e-4637-8d8a-1f178d4d2a0e
store_payment_method: true
transaction_context:
payment_link_id: 1e2d4f80-9c3e-4f5b-83aa-9e8d2b6a6c49
session_id: 1e2d4f80-9c3e-4f5b-83aa-9e8d2b6a6c49
type: SALE
properties:
amount:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_Amount"
billing_address:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_Address"
description: Optional billing address of the customer
browser_data:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_BrowserData"
description: An optional parameter that provides browser data to the issuing bank, potentially increasing authorization rates.
cardholder:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_Cardholder"
description: Optional cardholder information that increases authorization success with fewer payment challenges.
customer_contact:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_CustomerContact"
description: Optional customer contact details
initiator:
description: |
Identifies which actor initiated the transaction, the customer (such as in an immediate sale) or the merchant
(such as in a previously pre-authorized capture or a recurrent payment after the initial payment). Will default to customer if not provided.
This is primarily used to determine whether the consumer is present for the transaction and therefore SCA/3DS may be used.
enum:
- CUSTOMER
- MERCHANT
format: enum
type: string
line_items:
description: Optional list of line items for the transaction
items:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_LineItem"
type: array
merchant_reference_id:
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
payment_method:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_PaymentMethod"
description: Payment method to be used in the transaction
redirect_url:
description: URL to redirect the customer to after 3DS completes in case 3DS will be web based. Will be shared with the 3DS provider.
type: string
shipping_address:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_Address"
description: Optional shipping address for the order
store_payment_method:
description: When set to true, the payment method will be tokenized and a token_id returned in the response for future use.
type: boolean
example: true
store_id:
description: The unique identifier of a store
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
format: uuid
title: Store Id
type: string
type:
description: |
The transaction type. Use SALE for standard payments, PRE_AUTHORISATION to reserve funds for later capture, or ACCOUNT_VERIFICATION to verify a card and optionally tokenize it without charging the customer.
enum:
- SALE
- PRE_AUTHORISATION
- ACCOUNT_VERIFICATION
format: enum
type: string
required:
- amount
- initiator
- payment_method
- store_id
- type
title: ProcessTransactionRequestV2
type: object
Ecommerce_Transaction_Payments_-_Public_ProcessTransactionResponseV2:
description: The response for a transaction request
example:
online_transaction:
authentication_id: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
created_at: "2022-03-01T15:29:59Z"
issuer_result:
approval_code: "123456"
response_code: "00"
status: SUCCESS
token_response:
token_id: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
token_status: SUCCESS
transaction_id: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
updated_at: "2022-03-01T15:35:00Z"
type: ONLINE_TRANSACTION
properties:
online_transaction:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_OnlineTransaction"
redirect_transaction_response:
$ref: "#/components/schemas/Ecommerce_Transaction_Payments_-_Public_RedirectTransactionResponse"
type:
enum:
- ONLINE_TRANSACTION
- REDIRECT_TRANSACTION_RESPONSE
type: string
title: ProcessTransactionResponseV2
type: object
Ecommerce_Transaction_Payments_-_Public_RedirectTransactionResponse:
description: "The response for a transaction request where 3DS challenge is returned "
example:
authentication_id: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
created_at: "2022-03-01T15:29:59Z"
redirect_html: ...
status: PENDING
transaction_id: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
updated_at: "2022-03-01T15:35:00Z"
properties:
authentication_id:
description: The unique identifier for the authentication
example: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
format: uuid
type: string
created_at:
description: The datetime that the transaction was created (ISO 8601 format)
example: "2022-03-01T15:29:59Z"
format: date-time
type: string
redirect_html:
description: 3DS html content to present to a client
example: https://merchant.com/callback
type: string
status:
description: The status of the transaction
enum:
- SUCCESS
- FAILURE
- PENDING
example: PENDING
type: string
transaction_id:
description: The unique identifier for the new transaction
example: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
format: uuid
type: string
updated_at:
description: The datetime that the transaction was updated (ISO 8601 format)
example: "2022-03-01T15:35:00Z"
format: date-time
type: string
required:
- authentication_id
- created_at
- redirect_html
- status
- transaction_id
- updated_at
title: RedirectTransactionResponse
type: object
Ecommerce_Transaction_Payments_-_Public_TokenCreationResponse:
description: Details of the token which was created and if any failures will have the failure reason
example:
token_id: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
token_status: SUCCESS
properties:
brand:
description: "Brand of the card the token was created for. Populated on payment.succeeded.v1 webhook events when card details are known"
enum: [ "AMEX", "CALLIO", "CARDCO", "UNION_PAY", "DINERS", "DISCOVER", "DOXX", "GENERALI", "JCB", "KH", "MAESTRO", "MASTERCARD", "OTHER", "OTP", "PATIKA", "PREMIUM", "SODEXO", "UP", "VISA", "VITAMIN" ]
format: "enum"
nullable: true
type: "string"
failure_reason:
description: |
Why the token could not be created. Present when `token_status` is `FAILED`. Otherwise the field is either omitted or `null`, so handle both.
A failed token does not fail the payment: the payment result is reported separately in `status`.
- `MERCHANT_NOT_ENROLLED`: The store is not enrolled for card network tokens. Teya tries to enroll the store automatically on its first tokenization; this value means enrollment could not be completed. Contact Teya support.
- `MERCHANT_NOT_READY`: The store is enrolled, but the card networks have not finished setting it up. This can take up to 48 hours and resolves on its own. Try saving the card again later.
- `DECLINED_TOKENISATION`: The card network or issuer declined to create a token for this card. Ask the customer to save a different card.
- `EXPIRED_CARD`: The card has expired. Ask the customer to save a different card.
- `INELIGIBLE_CARD`: The card is not eligible for tokenization, for example because its issuer does not support network tokens. Ask the customer to save a different card.
- `INVALID_CARD`: The card details are not valid for tokenization. Ask the customer to check the card details or save a different card.
- `SERVICE_UNAVAILABLE`: The tokenization service was temporarily unavailable. Try saving the card again later.
- `UNKNOWN`: An unexpected error occurred while creating the token. Try again later and contact Teya support if the problem persists.
- `UNMAPPED`: An unrecognized error was returned by the tokenization service. Handle it like `UNKNOWN`.
New values may be added. Treat any value you do not recognize like `UNKNOWN`.
example: INELIGIBLE_CARD
nullable: true
type: string
last4:
description: Last four digits of the card used for the payment
example: "1234"
maxLength: 4
minLength: 4
nullable: true
pattern: "^[0-9]{4}$"
title: Last 4 Card Digits
type: string
token_id:
description: ID for the token which can be used for future payments
example: 5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
title: TokenId
type: string
token_status:
description: Status of the token creation
enum:
- SUCCESS
- FAILED
format: enum
type: string
token_type:
description: |
Type of token created. `CARD_TOKEN` for tokens created from card details, `WALLET_TOKEN` for tokens created from Apple Pay.
Store it with the `token_id` and send it back as `token_type` when charging the token.
enum:
- CARD_TOKEN
- WALLET_TOKEN
format: enum
nullable: true
type: string
required:
- token_status
title: TokenResponse
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_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_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_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:
- 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
If it's different, the request will be rejected with BAD_REQUEST
- 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.
Use SALE for standard payments or ACCOUNT_VERIFICATION to verify a card and optionally tokenize it without charging the customer.
enum:
- SALE
- 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_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_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_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_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
Teya_Digital_Receipts_Service_CreateReceiptRequest:
type: object
description: Request to initiate creation of digital receipts
example:
country_code: GB
language: en-GB
recipient_phone_numbers:
- "+123456789"
- "+987654321"
recipient_emails:
- johndoe@mail.com
- examplemail@email.com
properties:
country_code:
type: string
description: Country code (ISO 3166 format)
example: HU
language:
type: string
description: |
The language to be used to generate the receipt.
It should follow BCP-47 https://www.rfc-editor.org/info/bcp47 format.
If provided using the wrong format, the request will be rejected. If not provided, the receipt will be generated using the default language of the merchant.
example: en-GB
recipient_phone_numbers:
type: array
description: List of phone numbers to send the receipt link to
items:
type: string
description: List of phone numbers to send the receipt link to
example: "+123456789"
recipient_emails:
type: array
description: List of emails to send the receipt link to
items:
type: string
description: List of emails to send the receipt link to
example: email@example.com
receipt_email_type:
type: string
default: CUSTOMER
description: Type that indicates which email template to use
required:
- country_code
title: CreateReceiptRequest
Teya_Digital_Receipts_Service_CreateReceiptResponse:
type: object
description: Creates a url for customers to view their receipt.
example:
receipt_id: 01916f63-c6e0-75a9-9ef4-764ba287b2c6
transaction_id: 60cca1c7-38c5-4218-ba71-fb4a96836619
url: https://receipts.teya.com/01916f63-c6e0-75a9-9ef4-764ba287b2c6
properties:
receipt_id:
type: string
format: uuid
description: Id of the created receipt
transaction_id:
type: string
description: Transaction id, the same as in the request
url:
type: string
description: Url for receipt or error page in case or receipt generation failure
required:
- receipt_id
- transaction_id
- url
title: CreateReceiptResponse
Teya_Digital_Receipts_Service_Error:
type: object
description: Error response
example:
code: BAD_REQUEST
description: Invalid input
properties:
code:
type: string
format: enum
description: The error code
enum:
- BAD_REQUEST
- UNAUTHORISED
- FORBIDDEN
- INTERNAL_SERVER_ERROR
- TOO_MANY_REQUESTS
- NOT_FOUND
- NOT_ACCEPTABLE
description:
type: string
description: The description of the error
required:
- code
- description
title: Error
Payments_Refunds_Wrapper_API_Amount:
type: object
example:
amount: 100
currency: GBP
properties:
amount:
type: integer
format: int64
description: A positive integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1)
currency:
type: string
description: Currency code (e.g. `USD`, `GBP`, `EUR`) following ISO-4217 format.
required:
- amount
- currency
title: Amount
Payments_Refunds_Wrapper_API_DccResponse:
type: object
example:
cardholder_amount:
amount: 100
currency: CHF
conversion_rate: "0.9517"
markup: "0.03"
ecb_markup: "0.01"
properties:
cardholder_amount:
$ref: "#/components/schemas/Payments_Refunds_Wrapper_API_Amount"
description: |
The total amount refunded to the customer in the smallest currency unit (e.g., 100 cents to charge $1).
conversion_rate:
type: string
description: Conversion rate used to calculate the cardholder amount
markup:
type: string
description: Markup of the exchange rate
ecb_markup:
type: string
description: Markup of the exchange rate over the ECB exchange rate. Only provided when both currencies are EEA currencies.
required:
- cardholder_amount
- conversion_rate
- markup
title: DccResponse
CaptureRequest:
type: object
description: A request to capture a pre-authorised transaction
example:
amount: 1000
properties:
amount:
type: integer
format: int64
description: A positive integer representing the amount to capture in the smallest currency unit (e.g., 100 cents to charge $1). Must be less than or equal to the original authorisation amount.
required:
- amount
title: CaptureRequest
CaptureResponse:
type: object
description: A response to a capture request
example:
transaction_id: tr_5f7b1a3a-3b7a-4b1a-9b1a-3a3b7a4b1a9b
card_acceptor_id: "50001325"
status: SUCCESS
issuer_result:
approval_code: "123456"
response_code: "00"
processed_at: "2021-01-01T00:00:00.000Z"
properties:
transaction_id:
type: string
description: Unique identifier of the capture created
card_acceptor_id:
type: string
description: |
`mid` or `card_acceptor_id` (ISO 8583 field standard).
Used to uniquely identify the merchant in the transaction.
status:
type: string
description: The status of the capture
enum:
- SUCCESS
- FAILURE
- PENDING
status_reason:
type: string
description: Reason for `FAILURE` status
enum:
- ACCOUNT_INVALID
- CANNOT_VALIDATE_AUTHENTICATION
- CARD_COUNT_EXCEEDED
- CARD_DECLINED
- CARD_EXPIRED
- CARD_LIMIT_EXCEEDED
- CARD_NOT_ACTIVE
- DISABLED_ACCOUNT
- DO_NOT_HONOR
- ECOM_NEGATIVE_CARD_AUTHENTICATION_VERIFICATION
- EXCEEDS_AMOUNT_LIMIT
- FORMAT_ERROR
- INCORRECT_CARD_AUTHENTICATION
- INSUFFICIENT_FUNDS
- INVALID_CARD_NUMBER
- INVALID_TRANSACTION
- ISSUER_DECLINED
- LOST_OR_STOLEN
- MERCHANT_CONFIGURATION
- PIN_LIMIT_EXCEEDED
- PROCESSOR_UNAVAILABLE
- RESTRICTED_CARD
- SCA_PIN_REQUIRED
- SCA_REQUIRED
- SUSPECTED_FRAUD
- TEMPORARY_ISSUE_RETRY
- TIMEOUT
- TRANSACTION_NOT_ALLOWED
- UNABLE_TO_ROUTE_TRANSACTION
- UNSUPPORTED_ISSUER
- NEGATIVE_BALANCE_LIMIT
- OTHER
issuer_result:
$ref: "#/components/schemas/Payments_Gateway_Service_CaptureIssuerResult"
description: Result data for the capture according to issuer's response
title: IssuerResult
processed_at:
type: string
format: date-time
description: The date and time the capture was processed (in ISO 8601 with time-zone).
required:
- card_acceptor_id
- status
- transaction_id
title: CaptureResponse
Payments_Gateway_Service_CaptureIssuerResult:
type: object
example:
approval_code: "123456"
response_code: "00"
properties:
approval_code:
type: string
description: Identifier of the authorisation returned by the issuer. When the transaction is not authorised, this field is empty
response_code:
type: string
description: Response code returned by the issuer, indicating the result of the operation
title: CaptureIssuerResult
Payments_Refunds_Wrapper_API_RefundIssuerResult:
type: object
example:
approval_code: "123456"
response_code: "00"
properties:
approval_code:
type: string
description: Identifier of the authorisation returned by the issuer. When the transaction is not authorised, this field is empty
response_code:
type: string
description: Response code returned by the issuer, indicating the result of the operation
title: IssuerResult
RefundRequest:
type: object
description: A request to refund a transaction
example:
transaction_id: tr_87de9bea-b32d-4ef5-a481-b8ba48764325
amount: 100
properties:
transaction_id:
type: string
description: The id of the original transaction that needs to be refunded
minLength: 1
merchant_reference:
type: string
description: An ID referencing the transaction on the client's side
maxLength: 30
minLength: 1
amount:
type: integer
format: int64
description: A positive integer representing the total amount to refund in the smallest currency unit (e.g., 100 cents to charge $1). The currency is the same as the original transaction.
required:
- amount
- transaction_id
title: RefundRequest
RefundResponse:
type: object
description: A response to refund a transaction
example:
transaction_id: tr_87de9bea-b32d-4ef5-a481-b8ba48764325
refund_amount:
amount: 100
currency: GBP
card_acceptor_id: "5023045"
status: SUCCESS
issuer_result:
approval_code: "123456"
response_code: "00"
created_at: "2021-01-01T00:00:00.000Z"
dcc:
cardholder_amount:
amount: 100
currency: CHF
conversion_rate: "0.9517"
markup: "0.03"
ecb_markup: "0.01"
properties:
transaction_id:
type: string
description: Unique identifier of the refund created
status:
type: string
description: The status of the transaction
enum:
- SUCCESS
- FAILURE
- PENDING
status_reason:
type: string
description: Reason for `FAILURE` status
enum:
- ACCOUNT_INVALID
- CANNOT_VALIDATE_AUTHENTICATION
- CARD_COUNT_EXCEEDED
- CARD_DECLINED
- CARD_EXPIRED
- CARD_LIMIT_EXCEEDED
- CARD_NOT_ACTIVE
- DISABLED_ACCOUNT
- DO_NOT_HONOR
- ECOM_NEGATIVE_CARD_AUTHENTICATION_VERIFICATION
- EXCEEDS_AMOUNT_LIMIT
- FORMAT_ERROR
- INCORRECT_CARD_AUTHENTICATION
- INSUFFICIENT_FUNDS
- INVALID_CARD_NUMBER
- INVALID_TRANSACTION
- ISSUER_DECLINED
- LOST_OR_STOLEN
- MERCHANT_CONFIGURATION
- PIN_LIMIT_EXCEEDED
- PROCESSOR_UNAVAILABLE
- RESTRICTED_CARD
- SCA_PIN_REQUIRED
- SCA_REQUIRED
- SUSPECTED_FRAUD
- TEMPORARY_ISSUE_RETRY
- TIMEOUT
- TRANSACTION_NOT_ALLOWED
- UNABLE_TO_ROUTE_TRANSACTION
- UNSUPPORTED_ISSUER
- NEGATIVE_BALANCE_LIMIT
- OTHER
issuer_result:
$ref: "#/components/schemas/Payments_Refunds_Wrapper_API_RefundIssuerResult"
description: Result data for the refund according to issuer's response
title: IssuerResult
created_at:
type: string
format: date-time
description: The date and time the refund was created (in ISO 8601 with time-zone).
refund_amount:
$ref: "#/components/schemas/Payments_Refunds_Wrapper_API_Amount"
description: A positive integer representing the total amount refunded in the smallest currency unit (e.g., 100 cents to charge $1)
title: Amount
card_acceptor_id:
type: string
description: |
`mid` or `card_acceptor_id` (ISO 8583 field standard).
Used to unique identify the merchant in the transaction.
dcc:
$ref: "#/components/schemas/Payments_Refunds_Wrapper_API_DccResponse"
description: DCC data used for the refund
title: DCC
required:
- card_acceptor_id
- issuer_result
- refund_amount
- status
- transaction_id
title: RefundResponse
securitySchemes:
checkout_oauth_dev:
flows:
authorizationCode:
authorizationUrl: https://id.teya.xyz/oauth/v2/oauth-authorize
scopes: {}
tokenUrl: https://id.teya.xyz/oauth/v2/oauth-token
clientCredentials:
scopes: {}
tokenUrl: https://id.teya.xyz/oauth/v2/oauth-token
type: oauth2
checkout_oauth_prd:
flows:
authorizationCode:
authorizationUrl: https://id.teya.com/oauth/v2/oauth-authorize
scopes: {}
tokenUrl: https://id.teya.com/oauth/v2/oauth-token
clientCredentials:
scopes: {}
tokenUrl: https://id.teya.com/oauth/v2/oauth-token
type: oauth2
Ecommerce_Transaction_Payments_-_Public_oauth:
flows:
authorizationCode:
authorizationUrl: https://id.teya.com/oauth/v2/oauth-authorize
scopes: {}
tokenUrl: https://id.teya.com/oauth/v2/oauth-token
clientCredentials:
scopes: {}
tokenUrl: https://id.teya.com/oauth/v2/oauth-token
type: oauth2
pbl_oauth_dev:
flows:
authorizationCode:
authorizationUrl: https://id.teya.xyz/oauth/v2/oauth-authorize
scopes: {}
tokenUrl: https://id.teya.xyz/oauth/v2/oauth-token
clientCredentials:
scopes: {}
tokenUrl: https://id.teya.xyz/oauth/v2/oauth-token
type: oauth2
pbl_oauth_prd:
flows:
authorizationCode:
authorizationUrl: https://id.teya.com/oauth/v2/oauth-authorize
scopes: {}
tokenUrl: https://id.teya.com/oauth/v2/oauth-token
clientCredentials:
scopes: {}
tokenUrl: https://id.teya.com/oauth/v2/oauth-token
type: oauth2
Teya_Digital_Receipts_Service_oauth_prd:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://id.teya.com/oauth/v2/oauth-authorize
tokenUrl: https://id.teya.com/oauth/v2/oauth-token
scopes: {}
Payments_Refunds_Wrapper_API_oauth_prd:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://id.teya.com/oauth/v2/oauth-token
scopes:
terminal: ""
authorizationCode:
authorizationUrl: https://id.teya.com/oauth/v2/oauth-authorize
tokenUrl: https://id.teya.com/oauth/v2/oauth-token
scopes: {}