Overview

This document provides a detailed reference for all common and business parameters required when integrating with Oceanpayment APIs. It covers parameter formats, rules, and usage guidelines to ensure smooth API calls. Review these details before making API requests.

Request Flow

Request Parameters

All API Calls Require

Note

These parameters are mandatory for all API calls, usually related to authentication, request signing, and basic billing information.

Parameter	Type	Length	Required	Description	Example
account	string	6	Yes	Oceanpayment account number
terminal	string	8-12	Yes	Oceanpayment terminal number
signValue	string	64	Yes	Security signature to validate the request, SHA256 encrypted
key	string	64	Conditional	Oceanpayment public key Embedded-(required for embedded credit card integration)
backUrl	string	1-500	Yes	URL where the synchronous payment result will be returned
noticeUrl	string	1-500	No	Server callback URL for asynchronous payment notifications and other updates
methods	string	1-50	Yes	Payment method Use official method names.
order_number	string	1-50	Yes	Merchant’s order ID
order_currency	string	3	Yes	Transaction currency ISO 4217
order_amount	string	1-10	Yes	Transaction amount Up to 2 decimal places (e.g., 1.00) No transaction is needed if amount is 0

Billing Information

Parameter	Type	Length	Required	Description	Notes
billing_firstName	string	1-50	Yes	Customer first name To ensure consistent request signing, remove the following characters: leading/trailing spaces, double quotes, <, >, and single quotes.
billing_lastName	string	1-50	Yes	Customer last name To ensure consistent request signing, remove the following characters: leading/trailing spaces, double quotes, <, >, and single quotes.
billing_email	string	1-50	Yes	Customer email To ensure consistent request signing, remove the following characters: leading/trailing spaces, double quotes, <, >, and single quotes.
billing_phone	string	0-50	No	Customer phone
billing_country	string	1-100	Yes	Billing country ISO 3166
billing_state	string	1-100	Yes	Billing state/province/county ISO 3166-2
billing_city	string	0-500	No	Customer city
billing_address	string	0-500	No	Customer address
billing_zip	string	0-50	No	Postal code
billing_ip	string	0-50	Conditional	Customer IP. If multiple IPs are available, use the first one. Required for Embedded or Server to Server integrations.

Product Information

Information

Product information is required for settlement compliance. All related fields are mandatory.

Parameter	Type	Length	Required	Description	Example
productName	string	1-500	Yes	Product name(s) For multiple products, separate them with commas (,)
productNum	string	1-50	Yes	Product quantity For multiple products, separate them with commas (,)
productSku	string	1-500	Yes	SKU For multiple products, separate them with commas (,)
productPrice	string	1-500	Yes	Unit price For multiple products, separate them with commas (,)

Shipping Information

If shipping information is unavailable, billing info can be reused.

Parameter	Type	Length	Required	Description	Example
ship_firstName	string	1-50	No	Shipping first name
ship_lastName	string	1-50	No	Shipping last name
ship_email	string	1-50	No	Shipping email
ship_phone	string	0-50	No	Shipping phone
ship_country	string	1-100	No	Shipping country code ISO 3166
ship_state	string	1-100	No	Shipping state/province code ISO 3166-2
ship_city	string	0-500	No	Shipping city
ship_addr	string	0-500	No	Shipping street address
ship_zip	string	0-50	No	Shipping postal code

Business Parameters

Pass parameters according to the integration scenario requirements.

Parameter	Type	Length	Required	Description	Example
order_notes	string	0-500	No	Merchant notes, returned as-is
pages	string	0-50	No	Payment page terminal 0: Desktop (default) 1: Mobile
logoUrl	string	0-50	No	Logo displayed on payment page Hosted checkout or Embedded credit card only
language	string	0-50	No	Payment page language. If not specified, the language will default to the browser’s language. Supports 24 languages, default is English (en_US). Only applicable for Hosted Checkout and Embedded Credit Card integration.
cssUrl	string	0-50	No	URL of an online CSS file to override the payment page’s style Must start with https:// Overrides the default Oceanpayment payment page styles Only applicable for Hosted Checkout and Embedded integration.
pay_website	string	0-500	No	The merchant's source URL This field is required for SaaS/platform-built stores.

Additional Parameters (Alternative Payment)

Note

When using local payment methods, some additional parameters are required. Please pay attention to the specific parameter requirements for each payment method.

Parameter	Type	Length	Required	Description
pay_bankCode	string	1-50	Conditional	Supported bank code
pay_countryCode	string	1-50	Conditional	Supported country code
pay_installments	string	1-50	Conditional	Number of installments
pay_cpf	string	1-50	Conditional	Consumer CPF, CPF / taxpayer ID
pay_accountNumber	string	1-50	Conditional	ApplePay & GooglePay – Payment Token returned via direct integration WeChatPay/Alipay POS payments – Merchant-scanned customer authorization code WeChat authorization code format: ^1[0-6][0-9]16$ Alipay authorization code format: ^\d24$ Customer account number

Klarna Product Information

Note

When using Klarna, the total order amount must exactly match the sum of the itemized amounts; otherwise, the payment may fail.

Parameter	Type	Length	Required	Description	Example
itemList	string	1-500	Yes	Product node information JSON format, with a maximum of 25 nodes allowed.	{   "0": {     "type": "1",     "title": "book",     "sku": "#001",     "price": "100",     "quantity": "1",     "total_amount": "100.00",     "taxRate": "0.01",     "taxPrice": "1",     "image_url": "https://www.example.com/a.jpg",     "product_url": "https://www.example.com/a.html",     "remark": ""   },   "1": {     "type": "3",     "title": "discount",     "sku": "#002",     "price": "1",     "quantity": "1",     "total_amount": "1",     "taxRate": "0.01",     "taxPrice": "0.01",     "image_url": "",     "product_url": "",     "remark": ""   },   "2": {     "type": "4",     "title": "shipping_fee",     "sku": "#002",     "price": "1",     "quantity": "1",     "total_amount": "1",     "taxRate": "0.01",     "taxPrice": "0.01",     "image_url": "",     "product_url": "",     "remark": ""   },   "3": {     "type": "5",     "title": "sales_tax",     "sku": "#002",     "price": "1",     "quantity": "1",     "total_amount": "1",     "taxRate": "1",     "taxPrice": "1",     "image_url": "",     "product_url": "",     "remark": ""   } }

The total order amount consists of the following components:

• Product Amount：Unit price × quantity for each product
• Taxes: Applicable to products, shipping, or the entire order
• Shipping Fees: Shipping, courier, or delivery charges
• Discounts: Coupons, promotions, or other discounts

Total Order Amount = Product Amount + Taxes + Shipping Fees − Discounts

Airline Parameters

info

Applicable for airline payment scenarios only.

Parameter	Type	Length	Required	Description	Example
travel_totalTaxes	string	0-50	No	Taxes and Fees
travel_websiteLanguage	string	0-50	No	Website Language
travel_ticketNumber	string	1-200	Yes	Ticket number
travel_adult	string	1	Yes	Adult number
travel_child	string	1	Yes	Number of children
travel_infant	string	1	Yes	Number of babies
travel_electronicTicket	string	1	Yes	Is it an electronic ticket 1: True 0: False
+travel_customerInfoJson	object	-	Yes	Passenger node information (JSON format)

QuickPay

Create Quickpay ID

Note

When using the subscription scenario to create a Quickpay ID, the customer_id field is required.

Parameter	Type	Length	Required	Description	Example
customer_id	string	1-50	Yes	User ID A unique value used by the merchant to distinguish different users	NO123456

Initiate Payment

Note

When initiating a debit in subscription scenarios or quickpay, the quickpay_id field is required.

Parameter	Type	Length	Required	Description	Example
quickpay_id	string	1–200	Yes	A unique Quickpay ID generated by Oceanpayment Format: UUID	c6db7a28-7639-4d24-b7c5-6cd222c3e0fc

Response Parameters

Browser Synchronous Response:

• Each payment is returned via POST to the backUrl provided in the transaction request.
• The default return method is POST, but it can be changed to GET if needed.

Parameter	Type	Description	Example
response_type	string	Callback type 0: browser return 1: server async notification
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
signValue	string	Security signature to validate the request, SHA256 encrypted
methods	string	Payment method
order_number	string	Merchant order ID
order_currency	string	Currency
order_amount	string	Amount
order_notes	string	Notes
card_number	string	Card number
card_type	string	Card type
payment_country	string	Customer IP country
payment_id	string	Oceanpayment payment ID
payment_status	string	Transaction status -1: Pending (preauth) 0: Failed 1: Success
payment_authType	string	Transaction type 0: Sale 1: PreAuth non-3D 2: 3D non-PreAuth 3: 3D PreAuth
payment_details	string	Payment details for display on result page The website can process this and display it to the consumer on the payment result page.
payment_solutions	string	Suggested solution if payment fails The website can process this and display it to the consumer on the payment result page.
payment_risk	string	Failed risk rules (format: rule=score;...)
pay_barCode	string	Order print code

Asynchronous Notifications

Refer to the full list of Oceanpayment asynchronous notification parameters.