> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tazapay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Checkout Session
> This lets you create a checkout session for your customer by generating a Tazapay hosted payment page.
Tazapay has a [per transaction limit](https://support.tazapay.com/is-there-a-per-transaction-limit) depending on the payment method and currency. To avoid any errors, please refer to our FAQ.
## OpenAPI
````yaml post /v3/checkout
openapi: 3.1.0
info:
title: sandbox
version: '3'
servers:
- url: https://service-sandbox.tazapay.com
security:
- sec0: []
paths:
/v3/checkout:
post:
summary: Create Checkout Session
description: >-
This lets you create a checkout session for your customer by generating a
Tazapay hosted payment page.
operationId: create-checkout
requestBody:
content:
application/json:
schema:
type: object
required:
- invoice_currency
- amount
- customer_details
- success_url
- cancel_url
- transaction_description
properties:
invoice_currency:
type: string
description: >-
Invoice currency for the checkout session (in uppercase,
iso-4217 standard). By default, the invoice currency is the
holding currency for the transaction.
amount:
type: integer
description: >-
Amount in cents. For example if you want to charge $10.12
pass 1012 as the value. For decimal handling for various
currencies, refer to the guide here
format: int32
customer_details:
$ref: '#/components/schemas/CustomerDetails'
customer:
type: string
description: ID of the customer for the checkout session
success_url:
type: string
description: >-
URL where the customer is directed to after a successful
payment
cancel_url:
type: string
description: >-
The URL the customer will be directed to if they decide to
cancel payment and return to your website.
payment_methods:
type: array
description: >-
Specify the payment methods you want displayed for the
session. If you do not specify, the default payment methods
for the country are displayed to the customer
items:
type: string
remove_payment_methods:
type: array
description: Specify the payment methods you want removed for the session
items:
type: string
transaction_description:
type: string
description: >-
A short description to be displayed on the Tazapay hosted
checkout screen
shipping_details:
$ref: '#/components/schemas/ShippingDetails'
billing_details:
$ref: '#/components/schemas/BillingDetails'
expires_at:
type: string
description: >-
The time at which the checkout session is scheduled to
expire. If expired using the expire api, this will contain
the time that the checkout session expired at
format: date-time
transaction_documents:
type: string
description: Supporting documents for the transaction
format: json
metadata:
$ref: '#/components/schemas/MetadataInput'
reference_id:
type: string
description: Your unique identifier for the session
customer_fee_percentage:
type: integer
description: >-
An integer between 0 and 100. Percentage of processing fee
to be paid by the customer. Tazapay will charge the customer
an amount inclusive of the processing fee
format: int32
items:
type: array
description: List of items in the invoice
items:
properties:
name:
type: string
description: Name of the product the customer wants to buy
quantity:
type: integer
description: The number of the product the customer wants to buy
format: int32
amount:
type: integer
description: Unit Price of the product
format: int32
description:
type: string
description: Description of the product
required:
- name
- quantity
- amount
type: object
session_id:
type: string
description: >-
Session ID retrieved from the risk SDK
on_behalf_of:
type: string
description: >-
ID of the entity on whose behalf the checkout session is
being created. The entity must belong to the merchant
account. Format: `ent_*`
examples:
Request Example:
value:
invoice_currency: USD
amount: 100000
customer_details:
name: Andrea Lark
country: SG
email: andrea@example.com
phone:
calling_code: '65'
number: '87654321'
billing_details:
address:
city: Singapore
country: SG
line1: 1st Street
line2: 2nd Avenue
postal_code: '43004'
state: Singapore
label: Home
name: Andrea Lark
phone:
calling_code: '65'
number: '87654321'
shipping_details:
address:
city: Singapore
country: SG
line1: 1st Street
line2: 2nd Avenue
postal_code: '43004'
state: Singapore
label: Home
name: Andrea Lark
phone:
calling_code: '65'
number: '87654321'
success_url: https://mystore.com/success_page
cancel_url: https://mystore.com/try_again
webhook_url: https://mystore.com/internal/webhook
payment_methods:
- paynow_sgd
- card
transaction_description: 1 x T-shirt
expires_at: '2024-07-21T14:01:04.576356Z'
reference_id: mystore_order_00001
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
status: success
message: checkout session created successfully
data:
id: chk_cirsp2sl4ar024j0akj0
object: checkout
invoice_currency: USD
amount: 100000
amount_paid: 0
customer_details:
country: SG
email: andrea@example.com
name: Andrea Lark
phone:
calling_code: '65'
number: '87654321'
customer: cus_afobaifawnf
billing_details:
address:
city: Singapore
country: SG
line1: 1st Street
line2: 2nd Avenue
postal_code: '43004'
state: Singapore
label: Home
name: Andrea Lark
phone:
calling_code: '65'
number: '87654321'
shipping_details:
address:
city: Singapore
country: SG
line1: 1st Street
line2: 2nd Avenue
postal_code: '43004'
state: Singapore
label: Home
name: Andrea Lark
phone:
calling_code: '65'
number: '87654321'
success_url: https://mystore.com/success_page
cancel_url: https://mystore.com/try_again
webhook_url: https://mystore.com/internal/webhook
payment_methods:
- paynow_sgd
- card
transaction_description: 1 x trousers
expires_at: '2023-07-21T14:01:04.576356Z'
created_at: '2023-07-19T11:44:11.722049185Z'
url: >-
https://checkout.tazapay.com/transaction=ajfuibfainfaonfa
payment_status: unpaid
payment_status_description: null
status: active
payin: chk_cirsp2sl4ar024j0akj0
payment_attempts: []
latest_payment_attempt: ''
partially_paid: false
paid_in_excess: false
transaction_documents: []
reference_id: mystore_order_00001
metadata: null
schema:
type: object
properties:
status:
type: string
description: Indicates the status of the API response.
message:
type: string
description: Describes the result of the checkout session creation.
data:
$ref: '#/components/schemas/CheckoutData'
deprecated: false
components:
schemas:
CustomerDetails:
type: object
description: Details about the customer
required:
- name
- email
- country
properties:
name:
type: string
description: Name of the customer
email:
type: string
description: Email address of the customer
country:
type: string
description: 'ISO 3166 standard alpha-2 code. eg: SG, IN, US, etc.'
phone:
$ref: '#/components/schemas/Phone'
ShippingDetails:
type: object
description: Shipping details including recipient name, address and phone
properties:
name:
type: string
description: Name of the recipient
address:
$ref: '#/components/schemas/Address'
phone:
$ref: '#/components/schemas/Phone'
label:
type: string
description: Denotes the type of address (Example - home, work)
BillingDetails:
type: object
description: Billing details including name, address and phone
properties:
name:
type: string
description: Name of the billing contact
address:
$ref: '#/components/schemas/Address'
phone:
$ref: '#/components/schemas/Phone'
label:
type: string
description: Denotes the type of address (Example - home, work)
MetadataInput:
type: string
description: >-
Set of key-value pairs that can be attached to the object (JSON string
format)
format: json
example: '{"key1": "value1", "key2": "value2"}'
CheckoutData:
type: object
description: Contains all details related to a checkout session.
properties:
id:
type: string
description: Unique identifier for the checkout session.
object:
type: string
description: Type of object returned, typically 'checkout'.
invoice_currency:
type: string
description: Currency used for the invoice (ISO 4217 format).
amount:
type: integer
default: 0
description: Total amount of the checkout in smallest currency unit.
amount_paid:
type: integer
default: 0
description: Amount paid by the customer so far.
customer_details:
$ref: '#/components/schemas/CustomerDetails'
customer:
type: string
description: Unique identifier of the customer in the system.
billing_details:
$ref: '#/components/schemas/BillingDetails'
shipping_details:
$ref: '#/components/schemas/ShippingDetails'
success_url:
type: string
description: URL to redirect the customer after successful payment.
cancel_url:
type: string
description: URL to redirect the customer if the payment is cancelled.
webhook_url:
type: string
description: Merchant webhook URL for checkout event notifications.
payment_methods:
type: array
items:
type: string
description: Available payment methods for this checkout.
transaction_description:
type: string
description: Description of the transaction or items being purchased.
expires_at:
type: string
description: Timestamp at which the checkout session will expire.
created_at:
type: string
description: Timestamp at which the checkout session was created.
url:
type: string
description: Hosted checkout session URL for the customer to complete payment.
payment_status:
type: string
description: Current payment status of the checkout session.
payment_status_description:
type: string
description: Additional information describing the payment status.
status:
type: string
description: Overall status of the checkout session.
payin:
type: string
description: Linked payin identifier, if any.
payment_attempts:
type: array
items:
type: object
properties:
id:
type: string
object:
type: string
created_at:
type: string
amount:
type: integer
default: 0
charge_currency:
type: string
payin:
type: string
payment_method_details:
type: object
properties:
type:
type: string
paynow_sgd:
type: object
additionalProperties: true
refunded:
type: boolean
default: true
status:
type: string
status_description:
type: string
final_currency:
type: string
fx_transaction:
$ref: '#/components/schemas/FxTransaction'
metadata:
$ref: '#/components/schemas/Metadata'
description: Payment attempts associated with this checkout session.
latest_payment_attempt:
type: string
description: Identifier of the latest payment attempt if available.
partially_paid:
type: boolean
default: true
description: Indicates whether the checkout has been partially paid.
paid_in_excess:
type: boolean
default: true
description: Indicates whether an excess amount has been paid.
transaction_documents:
type: array
description: List of documents associated with this transaction.
reference_id:
type: string
description: External reference ID for the merchant's internal tracking.
metadata:
$ref: '#/components/schemas/Metadata'
on_behalf_of:
type: string
description: >-
ID of the entity on whose behalf the checkout session is created.
The entity must belong to the merchant account.
Phone:
type: object
description: Phone contact details
properties:
calling_code:
type: string
description: >-
Calling country code (for example, '1' for United States, '91' for
India)
number:
type: string
description: Phone Number
Address:
type: object
description: Address details
properties:
line1:
type: string
description: Address Line 1
line2:
type: string
description: Address Line 2
city:
type: string
description: Address city
state:
type: string
description: Address state
country:
type: string
description: Address country (ISO 3166-1 alpha-2 country code)
postal_code:
type: string
description: Postal Code
FxTransaction:
type: object
description: Details of an FX conversion transaction
properties:
exchange_rate:
type: number
description: FX exchange rate applied
final:
type: object
description: Final amount and currency after FX conversion
properties:
amount:
type: number
description: Final amount after FX conversion
currency:
type: string
description: Currency of the final amount
id:
type: string
description: FX transaction ID
initial:
type: object
description: Initial amount and currency before FX conversion
properties:
amount:
type: number
description: Initial amount before FX conversion
currency:
type: string
description: Currency of the initial amount
object:
type: string
description: Object type (fx_transaction)
Metadata:
type: object
description: Custom metadata key-value pairs attached to the object
additionalProperties:
type: string
nullable: true
securitySchemes:
sec0:
type: http
scheme: basic
````