openapi: 3.1.0
info:
title: Teya FX Captures Transactions 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: Transactions
name: Transactions
x-displayName: Transactions
paths:
/v3/transactions/online:
post:
description: 'API to process an online transaction v3.
<br><strong>Access Token Required scope:</strong> 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
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.
<br><strong>Access Token Required scope:</strong> 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
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
/v3/refunds:
post:
tags:
- Transactions
summary: Process a refund of a transaction
description: 'API to process the refund of a previous transaction.
<br><strong>Access Token Required scope:</strong> 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
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.
<br><strong>Access Token Required scope:</strong> 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
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/transactions/{id}/capture:
post:
tags:
- Transactions
summary: Capture a pre-auth
description: API to process a pre-auth capture
operationId: captureRequest
parameters:
- name: id
in: path
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.
'
required: true
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 transaction will be created.
'
maxLength: 64
minLength: 1
- name: Idempotency-Key
in: header
required: false
schema:
type: string
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:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- oauth: []
/v1/transactions/moto:
post:
tags:
- Transactions
summary: Process a mail order or telephone order transaction
description: API to process a transaction where card details are entered by the merchant via a virtual terminal
operationId: motoTransactions
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 transaction 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 transaction will be created.
'
maxLength: 64
minLength: 1
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MotoTransactionRequest'
required: true
responses:
'201':
description: Transaction processed
content:
application/json:
schema:
$ref: '#/components/schemas/MotoTransactionResponse'
'202':
description: Transaction processing
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorised
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'522':
description: Transaction not processed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'523':
description: Transaction failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- oauth: []
/v1/transactions/card-present:
post:
tags:
- Transactions
summary: Process a transaction with card present
description: API to process a transaction with a physical or virtual card present at a payment terminal
operationId: cardTransactions_2
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 transaction 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 transaction will be created.
'
maxLength: 64
minLength: 1
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRequest'
required: true
responses:
'201':
description: Transaction processed
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'202':
description: Transaction processing
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorised
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'523':
description: Origin Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- oauth: []
components:
schemas:
EncryptedTrack:
type: object
description: Encrypted track data from card reader
properties:
encryption_key_id:
type: string
description: Key identifier used for encryption
example: 5EE0
encrypted_track:
type: string
description: Encrypted track data
example: 5188340000000011D241212099999999
encryption_ksn:
type: string
description: Key serial number for encryption
example: '123456789012'
required:
- encryption_key_id
- encrypted_track
- encryption_ksn
title: EncryptedTrack
TransactionRequest:
type: object
description: A request to process a transaction
example:
type: SALE
entry_mode: CONTACT_MAGSTRIPE
verification_method: SIGNATURE
merchant_reference: '1234567890'
authentication_retry: false
amounts:
amount: 100
tip: 10
currency: USD
terminal_id: '12345678'
emv_data: 9F38039F1A02
terminal_data:
entry_mode_extra_capabilities:
- CONTACTLESS_EMV
cvm_extra_capabilities:
- CONSUMER_DEVICE
track_data:
encryption_key_id: 5EE0
encrypted_track: 5188340000000011D241212099999999
encryption_ksn: '123456789012'
pin_block:
block: 1234567890ABCDEF
format: ISO_FORMAT_0
encryption_key_id: 74FF
encryption_ksn: '123456789012'
transacted_at: '2021-01-01T00:00:00.000Z'
dcc:
quoted_at: '2024-01-01T10:00:00.000Z'
cardholder_amount:
amount: 78
currency: GBP
properties:
type:
type: string
format: enum
description: Whether this transaction is a SALE or PRE-AUTHORISATION.
enum:
- SALE
- PRE_AUTHORISATION
entry_mode:
type: string
format: enum
description: This field refers to how the card entry was made on the terminal device
enum:
- CONTACTLESS_EMV
- CONTACT_EMV
- CONTACT_MAGSTRIPE
- CONTACT_MAGSTRIPE_FALLBACK
- CONTACTLESS_MAGSTRIPE
- MANUAL_ENTRY
verification_method:
type: string
format: enum
description: This field refers to how the cardholder was verified on the terminal device
enum:
- CONSUMER_DEVICE
- NO_CVM
- ONLINE_PIN
- OFFLINE_ENCRYPTED_PIN
- OFFLINE_PLAINTEXT_PIN
- SIGNATURE
merchant_reference:
type: string
description: An identifier that can be used to reference the transaction on the merchant's side
maxLength: 60
minLength: 1
authentication_retry:
type: boolean
description: 'Whether this transaction is re-attempt with extra authentication provided (e.g.: SCA PIN request).'
amounts:
$ref: '#/components/schemas/RequestedAmounts'
description: The total amount charged to the customer
title: PurchaseAmount
terminal_id:
type: string
description: The ID of the terminal processing the transaction. Only required when using a non-Teya terminal.
maxLength: 8
minLength: 1
emv_data:
type: string
description: 'This field refers to the data hex-encoded as specified by the EMV standard. It includes data such as:
* Application Data: This includes data related to the card application, such as the Application Identifier (AID), Application Cryptogram, and other application-specific data.
* Cardholder Verification Method (CVM) Results: These indicate the outcome of cardholder verification methods used during the transaction, such as PIN verification or signature verification.
* Terminal Data: Information specific to the payment terminal, including Terminal Verification Results (TVR), Terminal Transaction Qualifiers (TTQ), and other terminal-specific data.
* Cryptogram Information: This includes various cryptograms used to secure the transaction, such as the Authorization Request Cryptogram (ARQC) and Authorization Response Cryptogram (ARPC).
* Transaction Data: Details related to the transaction, such as the amount, currency, transaction type, and other transaction-specific information.
This field should be encoded in TLV (tag-length-value ) format.
An example of `emv_data` is `5F2A02097882021C00` which is the hex-encoded value of the EMV tag `5F2A` with length `02` and value `0978` (which is the currency code for EUR) and the EMV tag
`82` with length `02` and value `1C00`.
'
terminal_data:
$ref: '#/components/schemas/TerminalData'
description: This field refers to the extra data about the terminal device used to initiate the card transaction
title: TerminalData
track_data:
$ref: '#/components/schemas/EncryptedTrack'
description: Encrypted track data for card present transaction
title: EncryptedTrack
pin_block:
$ref: '#/components/schemas/PinBlock'
description: Pin block data
title: PinBlock
transacted_at:
type: string
format: date-time
description: The datetime with time-zone when the transaction took place (ISO-8601)
card_data:
$ref: '#/components/schemas/CardData'
description: This field refers to the extra data about the card used to initiate the card transaction
title: CardData
dcc:
$ref: '#/components/schemas/DccRequest'
description: DCC data to be used for the transaction
title: DccRequest
required:
- amounts
- emv_data
- entry_mode
- track_data
- transacted_at
- type
title: TransactionRequest
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
InvalidParams:
type: object
description: Invalid parameter details
properties:
field:
type: string
description: The field that contains invalid data
example: amount.value
reason:
type: string
description: Reason why the field is invalid
example: must be greater than 0
required:
- field
- reason
title: InvalidParams
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
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'
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
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
RequestedAmounts:
type: object
example:
amount: 100
tip: 10
currency: USD
properties:
amount:
type: integer
format: int64
description: 'A positive integer representing the total amount to be charged to the customer in the smallest currency unit (e.g., 100 cents to charge $1).
Note that tip amount is included in this total
'
tip:
type: integer
format: int64
description: A positive integer representing the total amount that was tipped in the smallest currency unit (e.g., 100 cents to charge $1).
minimum: 0
currency:
type: string
description: Currency code (e.g. `USD`, `GBP`, `EUR`) following ISO-4217 format.
required:
- amount
- currency
title: PurchaseAmount
MotoIssuerResult:
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: MotoIssuerResult
CardData:
type: object
description: Card details for payment
properties:
number:
type: string
description: Card number (PAN)
pattern: ^[0-9]{13,19}$
example: '4111111111111111'
expiry_month:
type: string
description: Card expiry month (MM)
pattern: ^(0[1-9]|1[0-2])$
example: '12'
expiry_year:
type: string
description: Card expiry year (YYYY)
pattern: ^[0-9]{4}$
example: '2030'
cvv2:
type: string
description: Card verification value
pattern: ^[0-9]{3,4}$
example: '123'
required:
- number
- expiry_month
- expiry_year
title: CardData
PinBlock:
type: object
description: PIN block data
properties:
block:
type: string
description: Encrypted PIN block
example: 1234567890ABCDEF
format:
type: string
description: PIN block format
enum:
- ISO_FORMAT_0
- ISO_FORMAT_1
- ISO_FORMAT_3
example: ISO_FORMAT_0
encryption_key_id:
type: string
description: Key identifier used for encryption
example: 74FF
encryption_ksn:
type: string
description: Key serial number for encryption
example: '123456789012'
required:
- block
- format
- encryption_key_id
- encryption_ksn
title: PinBlock
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
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
Payments_Refunds_Wrapper_API_DccResponse:
type: object
example:
cardholder
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/teya/refs/heads/main/openapi/teya-transactions-api-openapi.yml