Vietnam-NINE_PAY - Onerway Payment API

Request

Body Params application/json

billingInformation

object (TransactionAddress)

账单信息，格式为JSON字符串

required

Billing Information

address

string

地址信息（账单或配送地址）

required

Address information (billing or shipping)

city

string

城市名称

required

City name

country

enum<string>

国家代码，请参考ISO 3166标准

required

Country code according to ISO 3166 standard

Allowed value:

string

电子邮件地址

required

Email address

firstName

string

名字

required

First name

identityNumber

string

证件号码

optional

Identity document number

lastName

string

姓氏

required

Last name

phone

string

电话号码

required

Phone number

postalCode

string

邮政编码

required

Postal code

province

enum<string>

省/州

required

State/province

Allowed value:

merchantCustId

string

客户在商户系统中的唯一标识

optional

Merchant Customer ID

merchantNo

enum<string>

商户号

required

Merchant number assigned by Onerway

Allowed value:

merchantTxnId

string

商户创建的交易订单号

required

Transaction order number created by the merchant

merchantTxnTime

string

商户交易时间，格式为yyyy-MM-dd HH:mm:ss

optional

Merchant transaction time in yyyy-MM-dd HH:mm:ss format

orderAmount

string

订单金额

required

Order amount

orderCurrency

enum<string>

订单币种，参考ISO 4217货币代码

required

Order currency according to ISO 4217 standard

Allowed value:

USD

shippingInformation

object (TransactionAddress)

配送信息，格式为JSON字符串

required

Shipping information in JSON string format

sign

null

签名

required

Signature string for request verification

txnOrderMsg

object (TxnOrderMsg)

交易订单信息，格式为JSON字符串

required

Transaction order information in JSON string format

enum<string>

持卡人浏览器的Accept请求头

required

Browser's Accept header from the cardholder's HTTP request

<= 2048 characters

Allowed value:

*/*

Example:

text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9

appId

enum<string>

商户应用程序ID，商户注册网站时Onerway会为商户创建

required

Unique identifier for the merchant's website/application. Can be obtained from Onerway merchant dashboard

<= 20 characters

Allowed value:

Example:

colorDepth

enum<string>

持卡人屏幕色深

required

Color depth of cardholder's screen. Obtained via window.screen.colorDepth

Allowed values:

162432

contentLength

enum<string>

持卡人浏览器内容长度头部以外的内容长度

required

Content length of the request body, excluding headers

Allowed values:

0102440961638465536

javaEnabled

boolean

持卡人浏览器是否开启java

required

Indicates if Java is enabled in cardholder's browser. Obtained via window.navigator.javaEnabled()

Example:

false

language

enum<string>

持卡人浏览器的语言

required

Browser language setting. Obtained via window.navigator.language

<= 64 characters

Allowed value:

en-US

Example:

zh-CN

products

array[object (Product) {5}]

商品信息数组，JSON字符串格式

required

Array of products in the current transaction

>= 1 items<= 3 items

returnUrl

enum<string>

同步返回地址

required

URL where the customer will be redirected after completing 3DS authentication

<= 256 characters

Allowed value:

Example:

https://docs.onerway.com/

notifyUrl

enum<string>

异步通知地址

required

Webhook URL for asynchronous notifications

Allowed value:

screenHeight

enum<string>

持卡人的屏幕高度

required

Screen height of cardholder's device. Obtained via window.screen.height

Allowed values:

4805686406677367407808008448518969159321024108011801200136614401600162018002160

screenWidth

enum<string>

持卡人的屏幕宽度

required

Screen width of cardholder's device. Obtained via window.screen.width

Allowed values:

32036037539039341241442876880082096210241280136614401536168019202048256034403840

timeZoneOffset

enum<string>

持卡人浏览器的时区偏移

required

Browser's timezone offset in minutes. Obtained via (new Date()).getTimezoneOffset()

Allowed values:

-840-720-660-600-540-480-420-360-300-240-180-120-60060120180240300360420480540600660720

transactionIp

string

商户客户的交易IP地址

required

IP address of the cardholder making the transaction

<= 64 characters

Example:

127.0.0.1

userAgent

enum<string>

持卡人的浏览器类型

required

Browser's User-Agent string. Obtained via window.navigator.userAgent

<= 2048 characters

Allowed value:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36

Example:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36

productType

enum<string>

产品类型

optional

Product type specifying the payment method category (LPMS for alternative payment methods specific to particular regions)

Allowed value:

LPMS

subProductType

enum<string>

子产品类型

optional

Sub-product type indicating the specific processing method (DIRECT for standard one-time payment)

Allowed value:

DIRECT

txnType

enum<string>

交易类型

optional

Transaction type defining the payment operation (SALE for immediate processing and settlement)

Allowed value:

SALE

lpmsInfo

object

本地支付方式信息

required

Configuration parameters for alternative payment methods specific to particular regions or payment ecosystems

lpmsType

enum<string>

本地支付方式类型

required

Local payment method type. Please refer to LpmsTypeEnum.

<= 64 characters

Allowed value:

Examples:

Alipay+KlarnaBoleto

bankName

null

银行名称，某些本地支付方式需要

optional

Bank name required for specific local payment methods. When lpmsType is EFT, refer to EFTBankNameEnum. When lpmsType is Przelewy24, refer to Przelewy24BankNameEnum.

iBan

null

银行账户，部分地区转账时需要

optional

International Bank Account Number required for transfers in certain regions.

walletAccountId

null

钱包/本地账户ID，部分地区转账时需要

optional

Wallet or local account identifier required for specific payment scenarios. Required when: 1) productType is LPMS and lpmsType is ATM_CARD (provide local bank account number), or 2) productType is PAYMENT_CODE (provide wallet payment code).

walletAccountName

null

钱包/本地账户名称，部分地区转账时需要

optional

Wallet or local account name required for specific payment scenarios. Mandatory when productType is LPMS and lpmsType is ATM_CARD, in which case the local bank account holder name must be provided.

prepaidNumber

null

预付费卡号

optional

Prepaid card number required for certain payment methods.

Example

{
  "billingInformation": {
    "address": "507 Medhurst Common",
    "city": "Wunschtown",
    "country": "US",
    "email": "Clemmie98@hotmail.com",
    "firstName": "Corrine",
    "identityNumber": "28614751574",
    "lastName": "O'Reilly",
    "phone": "13319247142",
    "postalCode": "22622-1917",
    "province": "CO"
  },
  "merchantCustId": "CustId-C2UX-233L",
  "merchantNo": "{{MERCHANT-NO}}",
  "merchantTxnId": "14646637-72b5-4e44-b8ab-646b3f5c7653",
  "merchantTxnTime": "2025-03-14 14:25:28",
  "orderAmount": "8",
  "orderCurrency": "USD",
  "shippingInformation": {
    "address": "432 Walker Mountain",
    "city": "West Mayra",
    "country": "US",
    "email": "Pedro64@gmail.com",
    "firstName": "Philip",
    "identityNumber": "00843584314",
    "lastName": "Treutel",
    "phone": "14507166681",
    "postalCode": "67598",
    "province": "CO"
  },
  "sign": null,
  "txnOrderMsg": {
    "accept": "*/*",
    "appId": "{{APPID}}",
    "colorDepth": "32",
    "contentLength": "4096",
    "javaEnabled": false,
    "language": "en-US",
    "products": [
      {
        "currency": "USD",
        "name": "pomegranate",
        "num": "1",
        "price": "371.79",
        "type": "consequat aliqua ea"
      }
    ],
    "returnUrl": "{{RETURN-URL}}",
    "notifyUrl": "{{WEBHOOK-ENDPOINT}}",
    "screenHeight": "736",
    "screenWidth": "1024",
    "timeZoneOffset": "720",
    "transactionIp": "207.110.164.55",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36"
  },
  "productType": "LPMS",
  "subProductType": "DIRECT",
  "txnType": "SALE",
  "lpmsInfo": {
    "lpmsType": "{{APM-NAME}}",
    "bankName": null,
    "iBan": null,
    "walletAccountId": null,
    "walletAccountName": null,
    "prepaidNumber": null
  }
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Body

object {0}

Example

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1704031498271133696",
    "responseTime": "2023-09-19 15:15:52",
    "txnTime": "2023-09-19 15:15:43",
    "txnTimeZone": "+08:00",
    "orderAmount": "20.00",
    "orderCurrency": "USD",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "R",
    "redirectUrl": "https://open-sea-global.alipayplus.com/api/open/v1/ac/cashier/self/codevalue/checkout.htm?codeValue=281666040092qSof8XXwp5AH3z0cQz8v4IxD&loadMode=2",
    "contractId": null,
    "tokenId": null,
    "eci": null,
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "redirectType": null,
    "sign": "ea85ec4db2aabf5edf6e2b96ae10514bf0c968bce2f22c5e6886e532e2143bc5"
  }
}