--- title: "Process an online transaction v3" method: POST path: "/v3/transactions/online" tags: ["Transactions"] --- # Process an online transaction v3 `POST /v3/transactions/online` ## Request - Base URL: `https://docs.teya.com` (the document declares no server; this is the origin it was published from) - URL: `https://docs.teya.com/v3/transactions/online` - Auth: OAuth 2 - Authorization code: `https://id.teya.com/oauth/v2/oauth-authorize` - Client credentials - Token URL: `https://id.teya.com/oauth/v2/oauth-token` - TypeScript: (a function with typed inputs; its response is checked against the schema) API to process an online transaction v3.
Access Token Required scope: transactions/online/create ## Headers - `Idempotency-Key` string, required: 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. - `User-Agent` string, required ## Request body - EcommerceTransactionPaymentsPublicProcessTransactionRequestV2: A request to process a transaction - `amount` EcommerceTransactionPaymentsPublicAmount, required: 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). - `currency` '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', enum, required: Currency code (e.g. `USD`, `GBP`, `EUR`) following ISO-4217 format. - `value` integer, required: The transaction amount in the smallest currency unit according to ISO 4217 format. - `billing_address` EcommerceTransactionPaymentsPublicAddress: Customer's address - `name` string: Name associated with the address - `city` string: City name - `country` string, required: ISO 3166-1 alpha-2 country code - `state` string: State or region - `street_address_line1` string: Primary street address - `street_address_line2` string: Secondary street address (apt, suite, etc.) - `street_address_line3` string: Additional address line - `zipcode` string: Postal/ZIP code - `browser_data` EcommerceTransactionPaymentsPublicBrowserData: Browser information transmitted during the authentication request process to enhance verification accuracy. - `accept_language` string: User preferred language from the browser - `ip_address` string, required: IP address of the browser - `screen_height` integer, required: Screen height of the browser - `screen_width` integer, required: Screen width of the browser - `user_agent` string: User agent of the browser - `cardholder` EcommerceTransactionPaymentsPublicCardholder: Information about the cardholder - `email` string: Email address of the cardholder - `name` string, required: Full name of the cardholder - `phone_number` string: Phone number of the cardholder - `customer_contact` EcommerceTransactionPaymentsPublicCustomerContact: Customer contact details - `phone_number` string: Customer's phone number - `email` string: Customer's email address - `initiator` 'CUSTOMER' | 'MERCHANT', enum, required: 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. - `line_items` EcommerceTransactionPaymentsPublicLineItem[]: Optional list of line items for the transaction - `description` string, required: This is a description for an item in the basket - `quantity` integer, required: The number of items, must be a positive value - `unit_price` integer, required: The price of a single item including VAT, Can be negative for discounts - `merchant_reference_id` string: An identifier that can be used to reference the transaction on the merchant's side. Overrides 'source_reference_id - `payment_method` EcommerceTransactionPaymentsPublicPaymentMethod, required - `apple_pay_authentication_data` EcommerceTransactionPaymentsPublicApplePayAuthenticationData: Represents the decrypted data from an Apple Pay payment token, including card details, transaction information, and merchant metadata. - `application_primary_account_number` string, required: Device-specific account number of the card that funds this transaction - `eci_code` string: ECI code for the transaction - `expiry_month` string, required: Card expiration month - `expiry_year` string, required: Card expiration year - `last_4_card_digits` string: Last four digits of the card behind the Apple Pay token. Use it to show the customer which card is saved. - `online_payment_cryptogram` string, required: Apple pay online payment cryptogram - `card` EcommerceTransactionPaymentsPublicCard - `cvc` string, required: 3 or 4 digit card verification code for the card - `expiry_month` string, required: 2-digit month of expiration for the card - `expiry_year` string, required: 4-digit year of expiration for the card - `number` string, required: Primary Account Number (PAN) of a card. Sent without spaces or dashes - `legacy_token` EcommerceTransactionPaymentsPublicLegacyToken: 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). - `token_id` string, required: 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. - `recurring_payment_type` 'CARD_ON_FILE' | 'RECURRING' | 'INSTALLMENT', enum, required: The type of recurring payment - `token` EcommerceTransactionPaymentsPublicToken: A saved payment method token for recurring or card-on-file transactions - `token_id` string, uuid, required: The unique identifier of the saved token - `recurring_payment_type` 'CARD_ON_FILE' | 'RECURRING' | 'INSTALLMENT', enum, required: The type of recurring payment - `token_type` 'CARD_TOKEN' | 'WALLET_TOKEN', enum, nullable: 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`. - `type` 'CARD' | 'TOKEN' | 'APPLE_PAY' | 'LEGACY_TOKEN', enum, required: Payment method type - `redirect_url` string: URL to redirect the customer to after 3DS completes in case 3DS will be web based. Will be shared with the 3DS provider. - `shipping_address` EcommerceTransactionPaymentsPublicAddress: Customer's address - `name` string: Name associated with the address - `city` string: City name - `country` string, required: ISO 3166-1 alpha-2 country code - `state` string: State or region - `street_address_line1` string: Primary street address - `street_address_line2` string: Secondary street address (apt, suite, etc.) - `street_address_line3` string: Additional address line - `zipcode` string: Postal/ZIP code - `store_payment_method` boolean: When set to true, the payment method will be tokenized and a token_id returned in the response for future use. - `store_id` string, uuid, required: The unique identifier of a store - `type` 'SALE' | 'PRE_AUTHORISATION' | 'ACCOUNT_VERIFICATION', enum, required: 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. ## Response `201` New transaction has been created and processed by host - EcommerceTransactionPaymentsPublicProcessTransactionResponseV2: The response for a transaction request - `online_transaction` EcommerceTransactionPaymentsPublicOnlineTransaction: The response for a transaction request - `authentication_id` string, uuid, required: The unique identifier for the authentication - `created_at` string, date-time, required: The datetime that the transaction was created (ISO 8601 format) - `issuer_result` EcommerceTransactionPaymentsPublicIssuerResult: Result data for the transaction according to issuer's response - `approval_code` string: Identifier of the authorisation returned by the issuer. When the transaction is not authorised, this field is empty - `response_code` string: 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) - `status` 'SUCCESS' | 'FAILURE' | 'PENDING', required: The status of the transaction - `status_reason` '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', enum: 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. - `token_response` EcommerceTransactionPaymentsPublicTokenCreationResponse: Details of the token which was created and if any failures will have the failure reason - `brand` 'AMEX' | 'CALLIO' | 'CARDCO' | 'UNION_PAY' | 'DINERS' | 'DISCOVER' | 'DOXX' | 'GENERALI' | 'JCB' | 'KH' | 'MAESTRO' | 'MASTERCARD' | 'OTHER' | 'OTP' | 'PATIKA' | 'PREMIUM' | 'SODEXO' | 'UP' | 'VISA' | 'VITAMIN', enum, nullable: Brand of the card the token was created for. Populated on payment.succeeded.v1 webhook events when card details are known - `failure_reason` string, nullable: 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`. - `last4` string, nullable: Last four digits of the card used for the payment - `token_id` string: ID for the token which can be used for future payments - `token_status` 'SUCCESS' | 'FAILED', enum, required: Status of the token creation - `token_type` 'CARD_TOKEN' | 'WALLET_TOKEN', enum, nullable: 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. - `transaction_id` string, uuid, required: The unique identifier for the new transaction - `updated_at` string, date-time, required: The datetime that the transaction was updated (ISO 8601 format) - `redirect_transaction_response` EcommerceTransactionPaymentsPublicRedirectTransactionResponse: The response for a transaction request where 3DS challenge is returned - `authentication_id` string, uuid, required: The unique identifier for the authentication - `created_at` string, date-time, required: The datetime that the transaction was created (ISO 8601 format) - `redirect_html` string, required: 3DS html content to present to a client - `status` 'SUCCESS' | 'FAILURE' | 'PENDING', required: The status of the transaction - `transaction_id` string, uuid, required: The unique identifier for the new transaction - `updated_at` string, date-time, required: The datetime that the transaction was updated (ISO 8601 format) - `type` 'ONLINE_TRANSACTION' | 'REDIRECT_TRANSACTION_RESPONSE' ## Other responses - `202`: New transaction has been created and still being processed (for example waiting for 3ds challenge to be completed) - `400`: Bad request due to wrong input - `401`: Unauthorized request because of missing or invalid authentication token - `403`: Forbidden request due to lack of permissions - `409`: Request is already being processed - `422`: Can not process the request because of an idempotency conflict - `500`: Internal Server Error --- [API](https://skmtc.dev/teya/apis/teya-apis-for-external-plugins.md) - [All operations](https://skmtc.dev/teya/apis/teya-apis-for-external-plugins/llms.txt) - [OpenAPI document](https://skmtc.dev/teya/apis/teya-apis-for-external-plugins/revisions/e26c4d895fa7?raw)