Overview

This document describes in detail the common parameters and business parameter Formats, rules, and requirements required when calling all order management API interfaces. Please read it carefully before initiating any requests.

Invocation flow

All API Calls Require

This section covers the common parameters required by all interfaces, usually related to authentication, signatures, 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

Order Status Query

Request

Parameter	Type	Length	Required	Description	Example
order_number	string	1-50	Yes	Website order number A maximum of 100 transactions can be queried at a time, with each transaction separated by a comma (",").

Response

Parameter	Type	Description	Example
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
signValue	string	Security signature to validate the request, SHA256 encrypted
paymentInfo	Object	When multiple paymentInfo entries appear for a payment order, they are ordered in descending order by transaction time.
order_currency	string	Transaction currency
order_amount	string	Transaction amount
order_number	string	Merchant’s order ID
order_notes	string	Merchant notes, returned as-is
methods	string	Payment method
payment_details	string	Payment details of this transaction
payment_dateTime	string	Transaction time Format: yyyy-mm-dd HH:mm:ss
order_sourceUrl	string	Order source URL
payment_id	string	Payment ID, the unique payment number assigned by Oceanpayment
payment_results	string	Order status query result
payment_details	string	Payment details of this transaction
payment_risk	string	Failed risk control rules
payment_authCode	string	The authorization code for this transaction. returns empty for non-credit card transactions
payment_eci	string	ECI value
payment_dateTime	string	Payment date GMT+8 Format: yyyy-mm-dd HH:mm:ss
auth_status	string	Pre-authorization status 0: Non-pre-authorization 1: Ovid 2: Pending 3: Captrue
payment_debitTime	string	Accounting time GMT+8 Format: yyyy-mm-dd HH:mm:ss
pay_barCode	string	Order print code/WeChatPay/Alipay payment transaction number
refund_status	string	Refund status 0: No refund 1: Refunded
refundList	string	refundList node information
chargeBack_status	string	Charged back status 0: Not charged back 1: Charged back
chargeBackList	string	chargeBackList node information
duplicate_status	string	Duplicate status For the same terminal, if there are more than two successful or pre-authorization pending transactions within 30 days, return 1; otherwise, return 0. 0: No 1: Yes
transactionList	string	transactionList node information
update_status	string	Update status 0: Not updated 1: Updated
networkToken	string	networkToken node information
payment_authType	string	Transaction type 0: Sale 1: PreAuth non-3D 2: 3D non-PreAuth 3: 3D PreAuth
threeDSecure	string	threeDSecure node information
pay_typeCode	string	Wallet return type, returned only for Alipay and WeChatPay

Successful Orders Query

Request

Parameter	Type	Length	Required	Description	Example
order_beginDate	string	19	Yes	Start time Format: yyyy-mm-dd HH:mm:ss
order_endDate	string	19	Yes	End time Format: yyyy-mm-dd HH:mm:ss
pages	string	5	No	Pagination

Response

Parameter	Type	Description	Example
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
signValue	string	Security signature to validate the request, SHA256 encrypted
results	string	Payment result
details	string	Payment details
count	string	Total number of records
totalpages	string	Total pages
pages	string	Current page
orderInfo	string	orderInfo node information

Business Orders Query

Request

Parameter	Type	Length	Required	Description	Example
order_beginDate	string	19	Yes	Start time Format: yyyy-mm-dd HH:mm:ss
order_endDate	string	19	Yes	End time Format: yyyy-mm-dd HH:mm:ss
pages	string	5	No	Pagination
count	string	3	No	Number of records per page - Default 10 records 10: 10 records 50: 50 records 100: 100 records
date_type	string	3	No	Date type - Default 0 0: Review time 1: Transaction time 2: Exception time

Response

Parameter	Type	Description	Example
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
signValue	string	Security signature to validate the request, SHA256 encrypted
results	string	Results code
details	string	Details
count	string	Total records
totalpages	string	Total pages
pages	string	Current page
orderInfo	string	orderInfo node information

Disputed Orders Query

Request

Parameter	Type	Length	Required	Description	Example
order_beginDate	string	19	Yes	Start time Format: yyyy-mm-dd HH:mm:ss
order_endDate	string	19	Yes	End time Format: yyyy-mm-dd HH:mm:ss
notice_type	string	0-50	No	Disputed type Default: query all disputes-period: Disputes period dispute: Dispute
payment_id	string	0-50	No	Payment ID, the unique payment number assigned by Oceanpayment
order_number	string	0-50	No	Merchant’s order ID

Response

Parameter	Type	Description	Example
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
signValue	string	Security signature to validate the request, SHA256 encrypted
results	string	Results code
details	string	Details
count	string	Total records
totalpages	string	Total pages
pages	string	Current page
orderInfo	string	orderInfo node information

Pre-Authorization

Request

Parameter	Type	Length	Required	Description	Example
payment_id	string	1-50	Yes	Payment ID, the unique payment number assigned by Oceanpayment
order_amount	string	0-50	No	Authorization amount If the amount is not provided, it is treated as a full authorization
payment_authType	string	1	Yes	Authorization type 1: Confirm authorization 2: Cancel authorization 3: Void (only supported for offline WeChatPay and Alipay scenarios)

Response

Parameter	Type	Description	Example
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
signValue	string	Security signature to validate the request, SHA256 encrypted
order_number	string	Merchant’s order ID
payment_id	string	Payment ID, the unique payment number assigned by Oceanpayment
payment_status	string	Payment status 1: Success 0: Failure
payment_details	string	Payment details

Refund Request

Request

Parameter	Type	Length	Required	Description	Example
payment_id	string	0-50	Yes	Payment ID, the unique payment number assigned by Oceanpayment
refund_number	string	0-50	No	Merchant internal refund transaction number
refund_type	string	1	Yes	Refund type 1: Full refund 2: Partial refund
refund_amount	string	1-10	Yes	Refund amount
refund_description	string	1-100	Yes	Refund description
refund_reference	string	0-50	No	Merchant internal refund reference number

Response

Parameter	Type	Description	Example
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
signValue	string	Security signature to validate the request, SHA256 encrypted
payment_id	string	Payment ID, the unique payment number assigned by Oceanpayment
order_number	string	Merchant’s order ID
refund_number	string	Merchant internal refund transaction number
refund_id	string	Refund ID, the unique refund number assigned by Oceanpayment
refund_results	string	Refund request result code
refund_description	string	Refund description
refund_reference	string	Merchant internal refund reference number

Refund Query

Request

Parameter	Type	Length	Required	Description	Example
refund_id	string	1-500	Conditions	Refund ID, the unique refund number assigned by Oceanpayment Refund request response fields With refund_number pick one of two
refund_number	string	1-50	Conditions	Merchant internal refund transaction number With refund_id pick one of two

Response

Parameter	Type	Description	Example
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
signValue	string	Security signature to validate the request, SHA256 encrypted
refund_id	string	Refund ID, the unique refund number assigned by Oceanpayment
refund_number	string	Merchant internal refund transaction number If refund_number is provided, it will be returned as-is
refund_queryNo	string	Refund voucher The refund voucher number provided by the issuing bank. Note that not all issuing banks provide this information
refund_check	string	Refund query result code
refund_description	string	Refund description

Tracking Numbers Upload

Request

Parameter	Type	Length	Required	Description	Example
payment_id	string	1-50	Conditions	Payment ID, the unique payment number assigned by Oceanpayment With order_number pick one of two
order_number	string	1-50	Conditions	Merchant’s order ID With payment_id pick one of two
tracking_number	string	1-200	No	Tracking number Uploading the same payment_id again will overwrite the previous tracking number If an order has multiple tracking numbers, separate them with a comma (",")
tracking_site	string	1-100	Yes	Tracking information website
tracking_handler	string	1-15	Yes	Tracking information added by

Response

Parameter	Type	Description	Example
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
signValue	string	Security signature to validate the request, SHA256 encrypted
payment_id	string	Payment ID, the unique payment number assigned by Oceanpayment
tracking_results	string	Tracking results

Customs Submission

Request

Parameter	Type	Length	Required	Description	Example
type	string	0-500	No	Submission type Each order can successfully initiate a customs submission request only once. To resend, set type = 2. 1: Customs submission 2: Resubmit (Retry submission)
payment_id	string	0-50	No	Payment ID, the unique payment number assigned by Oceanpayment
pay_userId	string	0-50	No	ID card
pay_userName	string	0-50	No	Name
price	string	1-100	Yes	Price
total_amount	string	1-100	Yes	Total amount
customs	string	1-100	Yes	Customs code
customs_number	string	1-100	Yes	Merchant customs registration number
customs_name	string	1-100	Yes	Merchant customs registration name
sub_order_number	string	0-100	No	Merchant sub-order number (required for split orders)
shipping_fee	string	1-100	Yes	Logistics fee
order_notes	string	0-500	No	Remark

Response

Parameter	Type	Description	Example
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
signValue	string	Security signature to validate the request, SHA256 encrypted
payment_id	string	Payment ID, the unique payment number assigned by Oceanpayment
type	string	Submission type
status	string	Submission status 0: Processing failed 1: Processed successfully 2: Pending Submission results are delivered via asynchronous notifications
details	string	Details description

Health Examination

Request

Parameter	Type	Length	Required	Description	Example
site	string	1-500	Yes	The primary domain name currently used by the website, without https://
key	string	0-256	No	Oceanpayment Public Key

Response

Parameter	Type	Description	Example
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
results	string	Verification result 1: If records exist and the status is reviewed (normal), there may be multiple records. As long as at least one record has the status reviewed (normal), it is considered as 1. 2: Records exist and all statuses are not reviewed (normal) 0: No records exist
site	string	Source URL whitelist, returned as-is

Card Bin Verification

Request

Parameter	Type	Length	Required	Description	Example
card_bin	array	-	Yes	First 6 digits of the card BIN A maximum of 100 card numbers can be queried at a time

Response

Parameter	Type	Description	Example
account	string	Oceanpayment account number
terminal	string	Oceanpayment terminal number
list	string	The results for each card BIN are organized into an array
check_results	string	Card BIN verification result 1: Successfully matched 0: Unrecognized
card_bin	string	First 6 digits of the card BIN, returned as-is
card_type	string	Card type
card_country	string	Card country