Integration guide
API conventions
- All endpoints use
POST, with anapplication/jsonrequest body. - Every request must include the common request headers.
merchantOrderNomust be unique within the merchant.- Request parameters, payment methods, and amount rules are defined on each country-specific endpoint page.
- An endpoint returning
code=200means only that the request was processed successfully; it does not mean that the transaction succeeded. - Confirm the transaction result using
data.status, query endpoints and callback notifications.
Test environment
The documentation console connects only to the test environments below and never sends requests to production. The platform identifies the order country from the domain.
| Country | Test environment |
|---|---|
| Indonesia | https://id-test-gateway.vellpay.com |
| South Korea | https://kr-test-gateway.vellpay.com |
| Cambodia | https://kh-test-gateway.vellpay.com |
| India | https://in-test-gateway.vellpay.com |
| Colombia | https://co-test-gateway.vellpay.com |
| Argentina | https://ar-test-gateway.vellpay.com |
| Brazil | https://br-test-gateway.vellpay.com |
| Vietnam | https://vn-test-gateway.vellpay.com |
Create an order
- The merchant generates a unique
merchantOrderNo. - Select the appropriate
paymentTypeorpayoutTypefor the country and business scenario. - Complete required parameters according to the endpoint documentation and generate
authorization. - Store the returned
tradeNofor troubleshooting and order tracking. - If a create request times out or the response is uncertain, query using the original merchant order number before creating another order.
Queries and callbacks
- Use the
merchantOrderNosupplied when creating the order to query the endpoint. - Callback services must implement signature verification and idempotency handling.
- An order may receive multiple callbacks because of network retries.
- If callback and query results differ, use the platform final order status and contact technical support to investigate the reversal.
- Merchants must store the complete status history, not only the latest callback.
Time and time zones
Business time uses the fixed GMT offset of the order country without daylight saving time; the text format is yyyy-MM-dd HH:mm:ss. The timestamp request header is a 13-digit Unix timestamp in milliseconds and does not use this text format.
| Country | Time zone |
|---|---|
| Indonesia | GMT+7 |
| Vietnam | GMT+7 |
| South Korea | GMT+9 |
| Cambodia | GMT+7 |
| India | GMT+5:30 |
| Colombia | GMT-5 |
| Argentina | GMT-3 |
| Brazil | GMT-3 |
Error handling
- Use response
msgto identify the field causing a parameter error. - Query the order after a network timeout to avoid duplicate creation.
- Server errors may be retried a limited number of times with exponential backoff.
- Insufficient balance, unconfigured payment methods, and merchant configuration errors must not be retried automatically.
- If the issue cannot be resolved, provide request time, environment, country,
appId, merchant order number, platform order number, andtid.
See Common error codes for full descriptions.