Card Checkout - Authorizaiton - Onerway Payment API

Request

Body Params application/json

Configuration for processing credit card authorization that verifies and reserves funds without immediate settlement

billingInformation

object

TransactionAddress

required

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

required

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:

sign

null

签名

required

Signature string for request verification

txnOrderMsg

object

TxnOrderMsg

required

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>

ColorDepthEnum

required

Allowed values:

162432

contentLength

enum<string>

ContentLengthEnum

required

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>

ScreenHeightEnum

required

Allowed values:

4805686406677367407808008448518969159321024108011801200136614401600162018002160

screenWidth

enum<string>

ScreenWidthEnum

required

Allowed values:

32036037539039341241442876880082096210241280136614401536168019202048256034403840

timeZoneOffset

enum<string>

TimeZoneOffsetEnum

required

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 (CARD for credit/debit card processing)

Allowed value:

CARD

subProductType

enum<string>

子产品类型

optional

Sub-product type indicating the specific processing method (DIRECT for standard card processing)

Allowed value:

DIRECT

txnType

enum<string>

交易类型

optional

Transaction type defining the payment operation (AUTH for fund reservation without capture)

Allowed value:

AUTH

Example

{
  "billingInformation": {
    "address": "6279 Mayfield Road",
    "city": "Karolannshire",
    "country": "US",
    "email": "Delores.Thiel1@gmail.com",
    "firstName": "Khalid",
    "identityNumber": "86032961732",
    "lastName": "Berge",
    "phone": "14064876575",
    "postalCode": "43936",
    "province": "CO"
  },
  "merchantCustId": "CustId-CIZ4-91M9",
  "merchantNo": "{{MERCHANT-NO}}",
  "merchantTxnId": "4f581f27-fe1a-4a80-8e10-2b3751ffb785",
  "merchantTxnTime": "2025-04-22 14:22:11",
  "orderAmount": "83",
  "orderCurrency": "USD",
  "shippingInformation": {
    "address": "639 Myrtle Green",
    "city": "Ubaldostead",
    "country": "US",
    "email": "Lucious.Feeney38@gmail.com",
    "firstName": "Lorna",
    "identityNumber": "42993160796",
    "lastName": "Pfannerstill",
    "phone": "16320585629",
    "postalCode": "83968",
    "province": "CO"
  },
  "sign": null,
  "txnOrderMsg": {
    "accept": "*/*",
    "appId": "{{APPID}}",
    "colorDepth": "32",
    "contentLength": "16384",
    "javaEnabled": false,
    "language": "en-US",
    "products": [
      {
        "currency": "USD",
        "name": "tomato",
        "num": "90",
        "price": "544.09",
        "type": "et ad quis laborum"
      },
      {
        "currency": "USD",
        "name": "lemon",
        "num": "100",
        "price": "31.19",
        "type": "et est minim in"
      },
      {
        "currency": "USD",
        "name": "aubergine",
        "num": "65",
        "price": "585.69",
        "type": "dolor deserunt minim"
      }
    ],
    "returnUrl": "{{RETURN-URL}}",
    "notifyUrl": "{{WEBHOOK-ENDPOINT}}",
    "screenHeight": "1800",
    "screenWidth": "800",
    "timeZoneOffset": "-540",
    "transactionIp": "187.178.122.99",
    "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": "CARD",
  "subProductType": "DIRECT",
  "txnType": "AUTH"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://sandbox-acq.onerway.com/txn/payment' \
--header 'Content-Type: application/json' \
--data-raw '{
    "billingInformation": {
        "address": "6279 Mayfield Road",
        "city": "Karolannshire",
        "country": "US",
        "email": "Delores.Thiel1@gmail.com",
        "firstName": "Khalid",
        "identityNumber": "86032961732",
        "lastName": "Berge",
        "phone": "14064876575",
        "postalCode": "43936",
        "province": "CO"
    },
    "merchantCustId": "CustId-CIZ4-91M9",
    "merchantNo": "YOUR-MERCHANT-NO",
    "merchantTxnId": "4f581f27-fe1a-4a80-8e10-2b3751ffb785",
    "merchantTxnTime": "2025-04-22 14:22:11",
    "orderAmount": "83",
    "orderCurrency": "USD",
    "shippingInformation": {
        "address": "639 Myrtle Green",
        "city": "Ubaldostead",
        "country": "US",
        "email": "Lucious.Feeney38@gmail.com",
        "firstName": "Lorna",
        "identityNumber": "42993160796",
        "lastName": "Pfannerstill",
        "phone": "16320585629",
        "postalCode": "83968",
        "province": "CO"
    },
    "sign": null,
    "txnOrderMsg": {
        "accept": "*/*",
        "appId": "YOUR-APPLICATION-ID",
        "colorDepth": "32",
        "contentLength": "16384",
        "javaEnabled": false,
        "language": "en-US",
        "products": [
            {
                "currency": "USD",
                "name": "tomato",
                "num": "90",
                "price": "544.09",
                "type": "et ad quis laborum"
            },
            {
                "currency": "USD",
                "name": "lemon",
                "num": "100",
                "price": "31.19",
                "type": "et est minim in"
            },
            {
                "currency": "USD",
                "name": "aubergine",
                "num": "65",
                "price": "585.69",
                "type": "dolor deserunt minim"
            }
        ],
        "returnUrl": "YOUR-RETURN-URL",
        "notifyUrl": "YOUR-WEBHOOK-ENDPOINT",
        "screenHeight": "1800",
        "screenWidth": "800",
        "timeZoneOffset": "-540",
        "transactionIp": "187.178.122.99",
        "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": "CARD",
    "subProductType": "DIRECT",
    "txnType": "AUTH"
}'

Responses

🟢200OK

application/json

Body

respCode

string

required

respMsg

string

required

data

object

required

transactionId

string

required

merchantTxnId

string

required

merchantNo

string

required

responseTime

string

required

txnTime

string

required

orderAmount

string

required

orderCurrency

string

required

txnAmount

string

required

txnCurrency

null

required

txnTimeZone

null

required

status

string

required

reason

null

required

redirectUrl

string

required

sign

string

required

contractId

string

required

tokenId

null

required

eci

null

required

transactionOrderNo

null

required

periodValue

null

required

lpmsType

null

required

qrCode

null

required

Example

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1710930229176258560",
    "merchantTxnId": "1654675447655",
    "merchantNo": "800209",
    "responseTime": "",
    "txnTime": "",
    "orderAmount": "35.00",
    "orderCurrency": "USD",
    "txnAmount": "",
    "txnCurrency": null,
    "txnTimeZone": null,
    "status": "U",
    "reason": null,
    "redirectUrl": "https://sandbox-v3-checkout.pacypay.com/checkout?key=4f698e88462d4eef8851dcd60edcd276",
    "sign": "20860d04d28cc55dcf950f86a86fa72587106d7004686016d07c44a568a5450a",
    "contractId": "",
    "tokenId": null,
    "eci": null,
    "transactionOrderNo": null,
    "periodValue": null,
    "lpmsType": null,
    "qrCode": null
  }
}