接入指引
调用约定
- 所有接口使用
POST，请求体格式为application/json。 - 每次请求必须携带公共请求头。
merchantOrderNo必须在商户范围内保持唯一。- 请求参数、支付方式和金额规则以对应国家接口页面为准。
- 接口返回
code=200只代表本次请求处理成功，不代表交易已经成功。 - 交易结果应结合
data.status、查询接口和回调通知确认。
测试环境
文档调试功能仅连接以下测试环境，不会向生产环境发送请求。平台根据域名识别订单所属国家。
| 国家 | 测试环境 |
|---|---|
| 印度尼西亚 | https://id-test-gateway.vellpay.com |
| 韩国 | https://kr-test-gateway.vellpay.com |
| 柬埔寨 | https://kh-test-gateway.vellpay.com |
| 印度 | https://in-test-gateway.vellpay.com |
| 哥伦比亚 | https://co-test-gateway.vellpay.com |
| 阿根廷 | https://ar-test-gateway.vellpay.com |
| 巴西 | https://br-test-gateway.vellpay.com |
越南测试域名配置完成后补充。
订单创建
- 商户生成唯一的
merchantOrderNo。 - 根据国家和业务场景选择
paymentType或payoutType。 - 按接口文档填写必填参数并生成
authorization。 - 保存接口返回的
tradeNo，用于问题排查和订单追踪。 - 创建请求超时或响应不确定时，先使用原商户订单号查询，不要立即创建新订单。
查询与回调
- 查询接口使用创建订单时的
merchantOrderNo。 - 回调服务必须实现签名验证和幂等处理。
- 同一笔订单可能因为网络重试收到多次回调。
- 回调与主动查询结果不一致时，以平台最终订单状态为准，并联系技术支持核查状态反转。
- 商户应保存完整的状态变化记录，不要只保存最后一次回调内容。
时间与时区
业务时间使用订单所属国家的当地时间，文本格式统一为 yyyy-MM-dd HH:mm:ss。timestamp 是鉴权使用的 13 位毫秒时间戳，不使用该文本格式。
| 国家 | 时区 |
|---|---|
| 印度尼西亚 | 以国家服务配置为准 |
| 越南 | Asia/Ho_Chi_Minh（GMT+7） |
| 韩国 | Asia/Seoul |
| 柬埔寨 | Asia/Phnom_Penh |
| 印度 | Asia/Kolkata |
| 哥伦比亚 | America/Bogota |
| 阿根廷 | America/Argentina/Buenos_Aires |
| 巴西 | 以国家服务配置为准 |
异常处理
- 参数错误应根据响应
msg定位具体字段。 - 网络超时后先查单，避免重复创建订单。
- 服务器错误可以有限次数重试，并使用指数退避策略。
- 余额不足、支付方式未配置和商户配置异常不应自动重试。
- 无法自行处理时，请提供请求时间、环境、国家、
appId、商户订单号、平台订单号和tid。
完整错误说明参见公共错误码。