Create a payment link

This API lets you create a payment link (Checkout URL) to send to your customer. When customers open this link, they can pay with any of the methods (VietQR, Card, Pay-by-Bank...) configured for the Merchant.

POST

URLhttps://open-api.tingee.vn/v1/payment-gateway/create-link

Create a payment link (Checkout URL) to send to the customer.

1. Request Headers

Header	Type	Required	Description
x-client-id	string	✓	The Merchant's Client ID issued by Tingee.
x-request-timestamp	string	✓	Time the request is sent (UNIX timestamp in milliseconds).
x-signature	string	✓	Request authentication signature that ensures data integrity.

2. Request Body (JSON)

Property	Type	Required	Description
requestId	string	✓	Request identifier. (Max: 36 chars, UUID v4)
orderId	string	✓	Order ID in your system. (Max: 100 chars; letters, digits, - and _ only)
amount	number	✓	Amount to pay. (Min: 2,000, Max: 10,000,000,000)
merchantId	number	✕	Merchant ID. (Required if you connect with a Master Merchant account).
currency	string	✕	Currency. Defaults to VND. (Max: 10 chars)
expireInMinute	number	✕	Link expiration time in minutes. Defaults to 30. (Min: 5, Max: 30)
description	string	✕	Short transaction description shown on the payment gateway. (Max: 200 chars)
orderInfo	string	✕	Additional internal order information. (Max: 1000 chars)
customerEmail	string	✕	Customer email.
vaAccountNumber	string	✕	Virtual account number, if you want to receive the payment into a specific account. (Max: 50 chars)
returnUrl	string	✕	URL (or App Scheme) that takes the customer back to your website/app after payment. (Max: 500 chars, valid URL)

Sample Request:

{
  "requestId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "orderId": "INV-0012345",
  "amount": 500000,
  "description": "Thanh toán đơn hàng INV-0012345",
  "returnUrl": "https://your-shop.com/checkout/success"
}

3. Response

The API returns the payment link (Checkout URL) in the data object.

Property	Type	Description
code	string	Result status code. 00 means success.
message	string	Detailed status message.
data	string	The payment link (Checkout URL) to redirect the customer to.

Sample successful Response (HTTP 200 OK):

{
  "code": "00",
  "message": "Success",
  "data": "https://payment-gateway.tingee.vn/checkout?token=base64urlEncodedToken&s=hmacSha256Signature"
}

4. Returned IPN (Webhook)

When the customer pays successfully or the order status changes (expired, cancelled), Tingee automatically sends an HTTP POST request (Webhook/IPN) with a JSON body to the IPN URL you configured on the Tingee Merchant Portal.

Property	Type	Description
requestId	string	Request ID of the webhook (UUID).
orderId	string	The corresponding order ID in your system.
amount	number	The original amount requested for the order.
paidAmount	number	The amount the customer actually paid.
description	string	Transaction description.
orderInfo	string	Additional order information (if any).
status	string	Order status (e.g. success, expired, canceled).
statusCode	string	Result status code (e.g. 00 means success).
billId	string	Transaction ID on the Tingee side (if any).
customerEmail	string	Customer's email.
paymentMethod	string	Payment method the customer used (e.g. qr).
providerTransactionCode	string	Transaction code recorded by the partner/bank.
paidAt	string	Time the payment was recorded (ISO 8601).
merchantId	number	Merchant identifier on Tingee.

Sample Webhook payload:

{
  "requestId": "e5700594-6c7f-4ce9-91d8-82d4e621ff78",
  "orderId": "SDK-1779119517852",
  "amount": 2000,
  "paidAmount": 2000,
  "description": "Thanh toan don hang test SDK",
  "orderInfo": null,
  "status": "success",
  "statusCode": "00",
  "billId": null,
  "customerEmail": null,
  "paymentMethod": "qr",
  "providerTransactionCode": "1927ee3a-7778-4500-9b4e-55363fa4a762",
  "paidAt": "2026-05-18T15:52:42.315Z",
  "merchantId": 29267
}