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	Required	Oceanpayment account number	995149
terminal	string	8-12	Required	Oceanpayment terminal number	99514901
signValue	string	64	Required	Security signature to validate the request, SHA256 encrypted	2f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
key	string	64	Conditional	Oceanpayment public key Embedded-(required for embedded credit card integration)	9c4f2a8d7e1b3c5f6a0d9e2b4c7f1a3d5e6b8c0f2a1d9e3c7b5f4a2d6e8c1f0a3b7d9e2c5f1a6b8d0c3e7f4a2b9c1d6e8f0a3b5c7d9e2f1a6c8b4d0e3f7a9c1b5d6e8f2a3c7b1d9e0f4a6c8b2d3e5f7a9c1d0b4e6f8a2c3d7b9e1f0a5c6d8b2e3f7a9c1d4b6e8f0a2c3d5b7e9f1a4c6d8e0b2f3a5c7d9e1f4a6b8c0d2e3f5a7b9c1d4e6f8a0c2d3b5e7f9a1c4d6e8b0f2a3c5d7e9f1a4b6c8d0e2f3a5b7c9d1e4f6a8b0c2d3e5f7a9
backUrl	string	1-500	Required	URL where the synchronous payment result will be returned	https://example.com/callback
noticeUrl	string	1-500	Optional	Server callback URL for asynchronous payment notifications and other updates	https://example.com/notify
methods	string	1-50	Required	Payment method Use official method names.	Credit Card
order_number	string	1-50	Required	Merchant’s order ID	123456789
order_currency	string	3	Required	Transaction currency ISO 4217	USD
order_amount	string	1-10	Required	Transaction amount Up to 2 decimal places (e.g., 1.00) No transaction is needed if amount is 0	1.00

Billing Information

Parameter	Type	Length	Required	Description	Notes
billing_firstName	string	1-50	Required	Customer first name To ensure consistent request signing, remove the following characters: leading/trailing spaces, double quotes, <, >, and single quotes.	John
billing_lastName	string	1-50	Required	Customer last name To ensure consistent request signing, remove the following characters: leading/trailing spaces, double quotes, <, >, and single quotes.	Wilson
billing_email	string	1-50	Required	Customer email To ensure consistent request signing, remove the following characters: leading/trailing spaces, double quotes, <, >, and single quotes.	customer@gmail.com
billing_phone	string	0-50	Conditional	Customer phone Required for Konbini	13106683312
billing_country	string	1-100	Required	Billing country ISO 3166	US
billing_state	string	1-100	Required	Billing state/province/county ISO 3166-2	NY
billing_city	string	0-500	Optional	Customer city	New York
billing_address	string	0-500	Optional	Customer address	350 5th Ave
billing_zip	string	0-50	Optional	Postal code	10024-3941
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.	127.0.0.1

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	Required	Product name(s) For multiple products, separate them with commas (,)	shoes
productNum	string	1-50	Required	Product quantity For multiple products, separate them with commas (,)	1
productSku	string	1-500	Required	SKU For multiple products, separate them with commas (,)	#123
productPrice	string	1-500	Required	Unit price For multiple products, separate them with commas (,)	1.00

Shipping Information

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

Parameter	Type	Length	Required	Description	Example
ship_firstName	string	1-50	Optional	Shipping first name	John
ship_lastName	string	1-50	Optional	Shipping last name	Wilson
ship_email	string	1-50	Optional	Shipping email	customer@gmail.com
ship_phone	string	0-50	Optional	Shipping phone	13106683312
ship_country	string	1-100	Optional	Shipping country code ISO 3166	US
ship_state	string	1-100	Optional	Shipping state/province code ISO 3166-2	NY
ship_city	string	0-500	Optional	Shipping city	New York
ship_addr	string	0-500	Optional	Shipping street address	350 5th Ave
ship_zip	string	0-50	Optional	Shipping postal code	10024-3941

Business Parameters

Pass parameters according to the integration scenario requirements.

Parameter	Type	Length	Required	Description	Example
order_notes	string	0-500	Optional	Merchant notes, returned as-is	test
pages	string	0-50	Optional	Payment page terminal 0: Desktop (default) 1: Mobile	0
logoUrl	string	0-50	Optional	Logo displayed on payment page Hosted checkout or Embedded credit card only	https://example.com/logo.png
language	string	0-50	Optional	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.	en_US
cssUrl	string	0-50	Optional	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.	https://example.com/style.css
pay_website	string	0-500	Optional	The merchant's source URL This field is required for SaaS/platform-built stores.	example.com

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	Apple Pay & Google Pay – 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
card_type	string	1-50	Conditional	Payment card type. It is required for direct integration with Google Pay and Apple Pay. Google Pay enum values: VISA, MASTERCARD, MAESTRO, JCB, ELO, DISCOVER, CHINAUNIONPAY, CARTESBANCAIRES, AMEX Apple Pay value: use paymentMethod.network returned in the Apple Pay Payment Token

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	Required	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

Airline parameters are only used in airline payment scenarios. They are not required for other transaction types.

Parameter	Type	Length	Required	Description	Example
travel_totalTaxes	string	0-50	Optional	Taxes and Fees
travel_websiteLanguage	string	0-50	Optional	Website Language
travel_adult	string	0-3	Optional	Adult number
travel_child	string	0-3	Optional	Number of children
travel_infant	string	0-3	Optional	Number of babies
travel_electronicTicket	string	1	Required	Is it an electronic ticket 1: True 0: False
travel_agencyCode	string	0-10	Optional	ATA Airport Code
travel_pnr	string	1-10	Required	PNR
travel_spnr	string	0-10	Optional	SPNR
ticket_deliveryMethod	string	1	Required	The way in which the ticket is delivered. The following lowercase values are accepted pick_up: The ticket is picked up in person. email: The ticket is sent by email. post: The ticket is sent by post. phone: The ticket is sent to a phone number.
+travel_customerInfoJson	object	-	Required	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	Required	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	Required	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	0
account	string	Oceanpayment account number	995149
terminal	string	Oceanpayment terminal number	99514901
signValue	string	Security signature to validate the request, SHA256 encrypted	A3F1C9D4E8B27F6A5C0D1E9F4B6A7C8D2E3F1A9B5C6D7E8F0A1B2C3D4E5F678
methods	string	Payment method	Credit Card
order_number	string	Merchant order ID	123456789
order_currency	string	Currency	USD
order_amount	string	Amount	1.00
order_notes	string	Notes	test
card_number	string	Card number	411111***1111
card_type	string	Card type	Visa
payment_country	string	Customer IP country	US
payment_id	string	Oceanpayment payment ID	26154125951032147852122
payment_status	string	Transaction status -1: Pending (preauth) 0: Failed 1: Success	1
payment_authType	string	Transaction type 0: Sale 1: PreAuth non-3D 2: 3D non-PreAuth 3: 3D PreAuth	0
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.	80000:Transaction Approved
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
payment_bankInfo	string	Parameters for Invoking the Bank SDK

Asynchronous Notifications

Refer to the full list of Oceanpayment asynchronous notification parameters.