TEteya
Hosted Checkout

Creates a new hosted checkout session

API to create a hosted checkout session. <br><strong>Access Token Required scope:</strong> checkout/sessions/create

post/v2/checkout/sessions

Request

  • Base URL
    https://docs.teya.com (the document declares no server; this is the origin it was published from)
  • Auth
    • OAuth 2
      Authorization codehttps://id.teya.xyz/oauth/v2/oauth-authorize
      Client credentials
      Token URLhttps://id.teya.xyz/oauth/v2/oauth-token
    • or OAuth 2
      Authorization codehttps://id.teya.com/oauth/v2/oauth-authorize
      Client credentials
      Token URLhttps://id.teya.com/oauth/v2/oauth-token
  • TypeScript
    A function with typed inputs. Its response is checked against the schema.

Headers

Idempotency-Keystring 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 session will be created.

User-Agentstring required
Example:YourCompany-Integration/1.0

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.

Request body

cancel_urlstring

URL to bring back the customer to the cart. If included in the call we will render the “Back” button in the HostedCheckout UI

customer_success_emailstring

If present, an e-mail is sent to the merchant customer upon successful payment with the receipt.

failure_urlstring

URL to redirect the customer once the transaction has finished with error

languagestring

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
merchant_referencestring

An identifier that can be used to reference the transaction on the merchant's side. Overrides 'source_reference_id

merchant_success_emailstring

If present, an e-mail is sent to the merchant upon successful payment with the receipt.

metadataobject

Metadata key-value pairs for the session. Maximum 10 keys allowed. Keys must not exceed 40 characters and values must not exceed 500 characters.

post_success_payment'SHOW_SUCCESS_PAGE' | 'REDIRECT' enum

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.

required_customer_fieldsstring[]

Customer fields that must be collected during checkout

save_payment_methodboolean

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.

store_idstring uuid

Store ID for the session. If not provided, it will be attempted to retrieve the store_id from the association with the client_id.

success_urlstring

URL to redirect the customer once the transaction has successfully finished

type'ACCOUNT_VERIFICATION' | 'PRE_AUTHORISATION' | 'SALE' enum required

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.

Example request

{
  "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"
}

Response

Session has been created

session_idstring uuid required

This is the id of the session that has been created and will be used to interact across different systems

session_urlstring url required

The hosted checkout session url that the merchant can use to redirect the customer once the session has been created

Example response

{
  "session_id": "14411456-79c8-4d8c-8498-f01907093b83",
  "session_url": "https://checkout.teya.com/pay/14411456-79c8-4d8c-8498-f01907093b83"
}

Changes

No recorded changes to this operation across all 1 revision of this API.