Subscription - Charge by Onerway - Onerway Payment API

Request

Body Params application/json

Configuration for establishing a recurring payment agreement that automatically bills the customer at defined intervals

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 (SUBSCRIBE for recurring billing arrangements)

Allowed value:

txnType

enum<string>

交易类型

optional

Transaction type defining the payment operation (SALE for immediate authorization and capture)

Allowed value:

SALE

cardInfo

object

卡信息

required

Card transaction information in JSON string format

holderName

enum<string>

持卡人姓名

required

Full name of the cardholder as it appears on the payment card

<= 64 characters

Allowed value:

CL BRW2

Example:

John Smith

cardNumber

enum<string>

卡号

required

Primary account number (PAN) of the payment card without spaces or separators

<= 16 characters

Allowed value:

4000000000002701

Example:

4000020951595032

month

enum<string>

有效期月份

required

Two-digit expiration month of the payment card (01-12)

<= 64 characters

Allowed value:

Example:

year

enum<string>

有效期年份

required

Two or four-digit expiration year of the payment card

<= 64 characters

Allowed value:

Example:

2024

cvv

enum<string>

安全码

required

Card Verification Value - security code on the back of the card (3-4 digits)

<= 64 characters

Allowed value:

123

Example:

123

subscription

Onerway发起扣款订阅

required

Core configuration parameters for establishing and managing recurring billing arrangements

One of

object

requestType

enum<string>

订阅请求类型

required

首购 | Initial Purchase

<= 1 characters

Allowed value:

selfExecute

enum<string>

订阅扣款方式

required

自动扣款 | Auto Debit

<= 1 characters

Allowed value:

productName

string | null

订阅商品名称

optional

Name of the product or service being subscribed to, displayed in payment statements and notifications

<= 256 characters

frequencyType

enum<string>

订阅频率类型

required

Unit of time measurement for the subscription billing cycle interval

<= 1 characters

Allowed values:

DWMY

bindCard

绑卡标志

required

Flag indicating that the payment card should be tokenized and stored for future subscription payments

Allowed value:

true

merchantCustId

string

商户客户ID

required

Unique identifier for the customer in the merchant's system, required for initial subscription setup

<= 40 characters

frequencyPoint

string

订阅频率点数

required

Numeric value defining the interval between billing cycles based on the frequencyType

<= 2 characters

notificationEmail

string <email> | null

通知邮箱

optional

Customer email address for receiving subscription-related notifications and receipts

<= 256 characters

metaData

string | null

元数据

optional

Custom JSON data field for merchant-specific information related to the subscription

<= 2048 characters

trialFromPlan

enum<string> | enum<null>

试用模式

optional

Indicates whether the subscription includes a trial period before regular billing begins

<= 256 characters

Allowed values:

trialDays

integer

试用天数

required

Number of days in the trial period before regular subscription billing begins

expireDate

string | null

过期日期

required

Specific calendar date when the subscription will automatically terminate

<= 10 characters

Match pattern:

^\d{4}-\d{2}-\d{2}$

Example

{
    "billingInformation": {
        "address": "205 Gail Summit",
        "city": "Port Desmondshire",
        "country": "US",
        "email": "Jon_Lindgren@gmail.com",
        "firstName": "Mylene",
        "identityNumber": "70082124392",
        "lastName": "Green",
        "phone": "15269654099",
        "postalCode": "65983",
        "province": "CO"
    },
    "merchantCustId": "CustId-M1SW-04UL",
    "merchantNo": "{{MERCHANT-NO}}",
    "merchantTxnId": "b884ba8e-618e-491f-80fe-f314ca84c6fd",
    "merchantTxnTime": "2025-05-19 13:36:54",
    "orderAmount": "709",
    "orderCurrency": "USD",
    "shippingInformation": {
        "address": "61320 E Cedar Street",
        "city": "Kathryneworth",
        "country": "US",
        "email": "Monserrate_Carter@gmail.com",
        "firstName": "Hattie",
        "identityNumber": "40437573569",
        "lastName": "Gusikowski",
        "phone": "15626167579",
        "postalCode": "51223",
        "province": "CO"
    },
    "sign": null,
    "txnOrderMsg": {
        "accept": "*/*",
        "appId": "{{APPID}}",
        "colorDepth": "24",
        "contentLength": "1024",
        "javaEnabled": true,
        "language": "en-US",
        "products": [
            {
                "currency": "USD",
                "name": "mangosteen",
                "num": "59",
                "price": "285.80",
                "type": "elit qui"
            },
            {
                "currency": "USD",
                "name": "apple",
                "num": "41",
                "price": "189.10",
                "type": "culpa aute"
            },
            {
                "currency": "USD",
                "name": "starfruit",
                "num": "2",
                "price": "125.29",
                "type": "cillum sit eiusmod nisi"
            }
        ],
        "returnUrl": "{{RETURN-URL}}",
        "notifyUrl": "{{WEBHOOK-ENDPOINT}}",
        "screenHeight": "568",
        "screenWidth": "1024",
        "timeZoneOffset": "-720",
        "transactionIp": "83.20.17.78",
        "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": "SUBSCRIBE",
    "txnType": "SALE",
    "cardInfo": {
        "holderName": "CL BRW2",
        "cardNumber": "4000000000002701",
        "month": "05",
        "year": "26",
        "cvv": "123"
    },
    "subscription": {
        "requestType": "0",
        "selfExecute": "1",
        "productName": "Rustic Frozen Pants",
        "frequencyType": "D",
        "bindCard": true,
        "merchantCustId": "CustId-M1SW-04UL",
        "frequencyPoint": "1",
        "notificationEmail": "Darron_Lehner@hotmail.com",
        "metaData": "ea amet id aliqua",
        "expireDate": "2025-12-23"
    }
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://sandbox-acq.onerway.com/v1/txn/doTransaction' \
--header 'Content-Type: application/json' \
--data-raw '{
    "billingInformation": {
        "address": "205 Gail Summit",
        "city": "Port Desmondshire",
        "country": "US",
        "email": "Jon_Lindgren@gmail.com",
        "firstName": "Mylene",
        "identityNumber": "70082124392",
        "lastName": "Green",
        "phone": "15269654099",
        "postalCode": "65983",
        "province": "CO"
    },
    "merchantCustId": "CustId-M1SW-04UL",
    "merchantNo": "YOUR-MERCHANT-NO",
    "merchantTxnId": "b884ba8e-618e-491f-80fe-f314ca84c6fd",
    "merchantTxnTime": "2025-05-19 13:36:54",
    "orderAmount": "709",
    "orderCurrency": "USD",
    "shippingInformation": {
        "address": "61320 E Cedar Street",
        "city": "Kathryneworth",
        "country": "US",
        "email": "Monserrate_Carter@gmail.com",
        "firstName": "Hattie",
        "identityNumber": "40437573569",
        "lastName": "Gusikowski",
        "phone": "15626167579",
        "postalCode": "51223",
        "province": "CO"
    },
    "sign": null,
    "txnOrderMsg": {
        "accept": "*/*",
        "appId": "YOUR-APPLICATION-ID",
        "colorDepth": "24",
        "contentLength": "1024",
        "javaEnabled": true,
        "language": "en-US",
        "products": [
            {
                "currency": "USD",
                "name": "mangosteen",
                "num": "59",
                "price": "285.80",
                "type": "elit qui"
            },
            {
                "currency": "USD",
                "name": "apple",
                "num": "41",
                "price": "189.10",
                "type": "culpa aute"
            },
            {
                "currency": "USD",
                "name": "starfruit",
                "num": "2",
                "price": "125.29",
                "type": "cillum sit eiusmod nisi"
            }
        ],
        "returnUrl": "YOUR-RETURN-URL",
        "notifyUrl": "YOUR-WEBHOOK-ENDPOINT",
        "screenHeight": "568",
        "screenWidth": "1024",
        "timeZoneOffset": "-720",
        "transactionIp": "83.20.17.78",
        "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": "SUBSCRIBE",
    "txnType": "SALE",
    "cardInfo": {
        "holderName": "CL BRW2",
        "cardNumber": "4000000000002701",
        "month": "05",
        "year": "26",
        "cvv": "123"
    },
    "subscription": {
        "requestType": "0",
        "selfExecute": "1",
        "productName": "Rustic Frozen Pants",
        "frequencyType": "D",
        "bindCard": true,
        "merchantCustId": "CustId-M1SW-04UL",
        "frequencyPoint": "1",
        "notificationEmail": "Darron_Lehner@hotmail.com",
        "metaData": "ea amet id aliqua",
        "expireDate": "2025-12-23"
    }
}'

Subscription - Charge by Onerway

Request

Request samples

Responses