Skip to content

Integration guide

API conventions

  • All endpoints use POST, with an application/json request body.
  • Every request must include the common request headers.
  • merchantOrderNo must be unique within the merchant.
  • Request parameters, payment methods, and amount rules are defined on each country-specific endpoint page.
  • An endpoint returning code=200 means 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.

CountryTest environment
Indonesiahttps://id-test-gateway.vellpay.com
South Koreahttps://kr-test-gateway.vellpay.com
Cambodiahttps://kh-test-gateway.vellpay.com
Indiahttps://in-test-gateway.vellpay.com
Colombiahttps://co-test-gateway.vellpay.com
Argentinahttps://ar-test-gateway.vellpay.com
Brazilhttps://br-test-gateway.vellpay.com
Vietnamhttps://vn-test-gateway.vellpay.com

Create an order

  1. The merchant generates a unique merchantOrderNo.
  2. Select the appropriate paymentType or payoutType for the country and business scenario.
  3. Complete required parameters according to the endpoint documentation and generate authorization.
  4. Store the returned tradeNo for troubleshooting and order tracking.
  5. 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 merchantOrderNo supplied 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.

CountryTime zone
IndonesiaGMT+7
VietnamGMT+7
South KoreaGMT+9
CambodiaGMT+7
IndiaGMT+5:30
ColombiaGMT-5
ArgentinaGMT-3
BrazilGMT-3

Error handling

  • Use response msg to 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, and tid.

See Common error codes for full descriptions.