Credit Card API

Endpoints

Live POST https://pay.onlinepay.ai/payment

Sandbox POST https://testpay.onlinepay.ai/payment

Modes

Direct mode

PCI compliance is required in this mode. The merchant system can capture the cardholder's card number information and transmit them to OlinePay, then the request is quickly verified and processed, and the payment result is returned directly.

Checkout

When you initiate a payment request, you will receive a checkout URL back from OnlinePay and be redirected to that checkout URL to submit your card number and other information, finally jump to the returnUrl to synchronize your payment results.

3DS

3DS is designed to reduce the risk of fraud and unauthorized transactions by verifying the identity of the cardholder. When making a 3DS-based payment, it redirects to a secure authentication page that allows the user to perform 3DS authentication.

note

OnlinePay will obtain the HTTP Header referer to verify the website source. The website source must be configured by OnlinePay to be verified. If you do not access the interface through a browser, you need to actively add a referer.

Request Parameters

Basic Information

Parameter	Type	Required	Description
merNo	integer	Yes	Merchant Number, Unique identifier assigned to the merchant by the onlinepay payment platform when registering with onlinepay
merOrderNo	string	Yes	Merchant Order Number, Each order must be unique, and each merchant order number can only be submitted once within 1 second
currencyCode	string	Yes	Please refer to Currency Code
sourceAmount	string	Yes	Total amount of the order, keep two decimals
returnUrl	string	Yes	Jump address after payment is completed (max 512 characters)
notifyUrl	string	No	Asynchronous notification address to notify the merchant of the final payment result (max 512 characters)
protestNotifyUrl	string	No	Asynchronous notification address to notify the merchant of the order chargeback (max 512 characters)
sign	string	Yes	Signature, MD5(merNo+merOrderNo+currencyCode+sourceAmount+PrivateKey) or RSA

Card Information

Parameter	Type	Required	Description
cardNo	string	Yes*	Card number, Checkout mode Can be empty
cardExpireMonth	string	Yes*	Expiry date of card (month), Checkout mode Can be empty
cardExpireYear	string	Yes*	Expiry date of card (year), Checkout mode Can be empty
cardSecurityCode	string	Yes*	CVV2/CSC, Checkout mode Can be empty

Billing Information

Parameter	Type	Required	Description
billingFirstName	string	Yes	First Name (max 50 characters)
billingLastName	string	Yes	Last name (max 50 characters)
billingAddress1	string	Yes	Billing address 1 (max 128 characters)
billingAddress2	string	No	Billing address 2 (max 128 characters)
billingCity	string	Yes	City of residence (bill) (max 100 characters)
billingState	string	Yes	State Name (Bill) (max 100 characters)
billingCountry	string	Yes	International ISO country abbreviation, Refer to the Country Code (max 2 characters)
billingZipCode	string	Yes	Postal Code (max 20 characters)
billingPhone	string	Yes	Billing phone (max 20 characters)
billingEmail	string	Yes	Billing email (max 100 characters)

Shipping Information (Required for physical goods)

Parameter	Type	Required	Description
shippingFirstName	string	Yes**	Consignee's first name (max 50 characters)
shippingLastName	string	Yes**	Consignee's last name (max 50 characters)
shippingAddress1	string	Yes**	Receiving address details 1 (max 128 characters)
shippingAddress2	string	Yes**	Receiving address details 2 (max 128 characters)
shippingCity	string	Yes**	Receiving city (max 100 characters)
shippingState	string	Yes**	Receiving continent, province (max 100 characters)
shippingCountry	string	Yes**	Receiving country, Refer to the Country Code table (max 2 characters)
shippingZipCode	string	Yes**	Consignee's zip code (max 20 characters)
shippingPhone	string	Yes**	Consignee phone (max 20 characters)
shippingEmail	string	Yes**	Shipping email (max 100 characters)

Additional Information

Parameter	Type	Required	Description
userAgent	string	Yes	Cardholder browser UserAgent (max 128 characters)
ipAddress	string	Yes	Cardholder IP address (max 64 characters)
productInfoList	array[object]	Yes	Product list
- sku	string	Yes	Product ID (max 64 characters)
- productName	string	Yes	Product name (max 128 characters)
- price	string	Yes	Commodity price (max 16 characters)
- quantity	string	Yes	Quantity of commodity (max 16 characters)
version	string	Yes	V3.0.0
paymentMethod	integer	No	0: normal, 1: subscribe
paymentInterval	integer	No	0: weekly, 1: monthly, 2: yearly
cardId	integer	No	Binding bank card id

* Required in Direct mode, can be empty in Checkout mode ** Required for physical goods, not needed for virtual goods

Example Request

{
  "merNo": 111111,
  "merOrderNo": "222222",
  "currencyCode": "USD",
  "sourceAmount": "100.05",
  "returnUrl": "https://example.com",
  "notifyUrl": "https://example.com/notify",
  "protestNotifyUrl": "https://example.com/protestNotify",
  "sign": "906FDF4880B00B00281F2AB61AE9A721",
  "cardNo": "4242424242424242",
  "cardExpireMonth": "01",
  "cardExpireYear": "2022",
  "cardSecurityCode": "335",
  "billingFirstName": "Tati",
  "billingLastName": "Moore",
  "billingAddress1": "123 Main St",
  "billingCity": "Anytown",
  "billingState": "CA",
  "billingCountry": "US",
  "billingZipCode": "12345",
  "billingPhone": "1234567890",
  "billingEmail": "[email protected]",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "ipAddress": "192.168.1.1",
  "productInfoList": [
    {
      "sku": "PROD001",
      "productName": "Example Product",
      "price": "100.05",
      "quantity": "1"
    }
  ],
  "version": "V3.0.0"
}

Responses Body

Parameter	Type	Required	Description
code	string	Yes	If the value is 00000, it will return success, other please refer to Error Code
message	string	Yes	Interface returns description
data	object	Yes**	Request response data
-tradeNo	string	Yes	The flow number generated after each order payment (unique marker)
-payCode	string	Yes	Payment status code(Where: 1 means payment failure, 0 means payment success, 2 means pending)
-payUrl	string	Yes**	If the paycode is 2, redirect to this address
-merOrderNo	string	Yes	Corresponds to the [OrderNo] parameter of the order submission parameter
-cardId	string	Yes**	Binding bank card id

Example Responses

{
    "code":"00000",
    "message":"SUCCESS",
    "data":{
        "payCode":0,
        "tradeNo":"3333333",
        "merorderNo":"222222",
        "payUrl":"https://abc.com/"
     }
}