概述

本文档详细描述了调用支付功能时所需的通用参数、业务参数的格式、规则和要求。仅适用于Klarna和其他本地支付场景，请在发起请求前仔细阅读。

调用流程

请求参数

通用参数(所有接口必传)

注意

这部分是所有接口都需要的公共参数，通常与身份认证、签名和账单基础信息相关。

参数名	类型	长度	是否必填	描述	示例
account	string	6	是	Oceanpayment账户号	995149
terminal	string	8-12	是	Oceanpayment终端号	99514901
signValue	string	64	是	安全签名，用于验证交易的安全性，使用SHA256加密	2f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
key	string	64	有条件	Oceanpayment公钥 嵌入式-信用卡集成必传	9c4f2a8d7e1b3c5f6a0d9e2b4c7f1a3d5e6b8c0f2a1d9e3c7b5f4a2d6e8c1f0a3b7d9e2c5f1a6b8d0c3e7f4a2b9c1d6e8f0a3b5c7d9e2f1a6c8b4d0e3f7a9c1b5d6e8f2a3c7b1d9e0f4a6c8b2d3e5f7a9c1d0b4e6f8a2c3d7b9e1f0a5c6d8b2e3f7a9c1d4b6e8f0a2c3d5b7e9f1a4c6d8e0b2f3a5c7d9e1f4a6b8c0d2e3f5a7b9c1d4e6f8a0c2d3b5e7f9a1c4d6e8b0f2a3c5d7e9f1a4b6c8d0e2f3a5b7c9d1e4f6a8b0c2d3e5f7a9
backUrl	string	1-500	是	同步返回支付信息的网站URL地址	https://example.com/callback
noticeUrl	string	1-500	否	服务器回调URL地址，用于交易结果推送及其他业务状态推送	https://example.com/notify
methods	string	1-50	是	支付方式 传值请参考支付方式名称(methods)	Credit Card
order_number	string	1-50	是	网站订单号	123456789
order_currency	string	3	是	订单号的交易币种 采用国际标准ISO 4217代码	USD
order_amount	string	1-10	是	订单号的交易金额 最大支持小数点后2位数，如：1.00 如果交易金额为0，不需要发送交易	1.00

账单信息

参数名	类型	长度	是否必填	描述	示例
billing_firstName	string	1-50	是	消费者的名 为了保证签名一致，需要过滤字符：首尾空格，双引号，小于号，大于号，单引号	John
billing_lastName	string	1-50	是	消费者的姓 为了保证签名一致，需要过滤字符：首尾空格，双引号，小于号，大于号，单引号	Wilson
billing_email	string	1-50	是	消费者的邮箱 为了保证签名一致，需要过滤字符：首尾空格，双引号，小于号，大于号，单引号	customer@gmail.com
billing_phone	string	0-50	有条件	消费者的电话 日本便利店支付为必传	13106683312
billing_country	string	1-100	是	消费者的账单国家 采用国际标准ISO 3166代码	US
billing_state	string	1-100	是	消费者的州（省、郡） 采用国际标准ISO 3166-2代码	NY
billing_city	string	0-500	否	消费者的城市	New York
billing_address	string	0-500	否	消费者的详细地址	350 5th Ave
billing_zip	string	0-50	否	消费者的邮编	10024-3941
billing_ip	string	0-50	有条件	消费者的ip地址 由网站进行获取，如果获取到多个ip，则取第一个 嵌入式，服务器对服务器集成必传	127.0.0.1

产品信息

信息

产品信息为结汇合规要求，相关字段均为必传参数。

参数名	类型	长度	是否必填	描述	示例
productName	string	1-500	是	产品名称 多个产品用英文,隔开	shoes
productNum	string	1-50	是	产品数量 多个产品用英文,隔开	1
productSku	string	1-500	是	产品SKU 多个产品用英文,隔开	#123
productPrice	string	1-500	是	产品单价 多个产品用英文,隔开	1.00

收货信息

当网站没有收货信息时，可以用账单信息的值进行传值。

参数名	类型	长度	是否必填	描述	示例
ship_firstName	string	1-50	否	收货人的名	John
ship_lastName	string	1-50	否	收货人的姓	Wilson
ship_email	string	1-50	否	收货人的邮箱	customer@gmail.com
ship_phone	string	0-50	否	收货人的电话	13106683312
ship_country	string	1-100	否	收货人的账单国家 采用国际标准ISO 3166代码	US
ship_state	string	1-100	否	收货人的州（省、郡） 采用国际标准ISO 3166-2代码	NY
ship_city	string	0-500	否	收货人的城市	New York
ship_addr	string	0-500	否	收货人的详细地址	350 5th Ave
ship_zip	string	0-50	否	收货人的邮编	10024-3941

业务参数

按对接场景需求进行传参。

参数名	类型	长度	是否必填	描述	示例
order_notes	string	0-500	否	订单备注信息，返回时则原样返回	test
pages	string	0-50	否	支付页面终端 0:PC端 (默认) 1:移动端	0
logoUrl	string	0-50	否	用于显示在支付页面上的logo URL 只支持托管结账和嵌入式-信用卡集成	https://example.com/logo.png
language	string	0-50	否	支付页面语言，不传值默认根据浏览器语言进行适配 支持24种语言，默认英语（en_US）， 只支持托管结账和嵌入式-信用卡集成	en_US
cssUrl	string	0-50	否	在线CSS样式文件链接，用于重写支付页面的样式 必须为https协议开头， 覆盖Oceanpayment支付页面原有的样式， 只支持托管结账和嵌入式集成	https://example.com/style.css
pay_website	string	0-500	有条件	商家的来源网址 SaaS/平台对接时为必填项	example.com

附加参数(本地支付)

注意

在使用本地支付方式时，除通用请求参数外，部分支付方式还需传递额外的特定参数。请根据不同支付方式的接口要求，正确传入对应参数。

参数名	类型	长度	是否必填	描述
pay_bankCode	string	1-50	有条件	支持的银行代码
pay_countryCode	string	1-50	有条件	支持的国家代码
pay_installments	string	1-50	有条件	分期数
pay_cpf	string	1-50	有条件	消费者的CPF，纳税人识别号
pay_accountNumber	string	1-50	有条件	Apple Pay&Google Pay直连返回的Payment Token参数 微信/支付宝面对面付款-商家扫码消费者支付授权码 微信授权码格式要求：^1[0-6][0-9]16$ 支付宝授权码格式要求：^\d{16,24}$ 消费者账户号码
card_type	string	1-50	有条件	支付卡种。Google Pay、Apple Pay直连支付必传 Google Pay枚举：VISA, MASTERCARD, MAESTRO, JCB, ELO, DISCOVER, CHINAUNIONPAY, CARTESBANCAIRES, AMEX Apple Pay传值：Apple Pay Payment Token返回的 paymentMethod.network

Klarna产品信息

注意

在使用Klarna支付时，itemList参数为必传。每个订单的总金额必须与明细金额严格一致，否则会导致支付失败。

参数名	类型	长度	是否必填	描述	示例
itemList	string	1-500	是	产品节点信息 Json格式，最多只允许25个节点	{   "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": ""   } }

订单总价由以下部分组成：

• 商品金额：每个商品单价 × 数量
• 税费：可针对商品、物流或订单全局的税额
• 物流费用：运费、快递费等
• 折扣：优惠券、满减、促销折扣等

订单总价 = 商品金额 + 税费 + 物流费用 - 折扣。

航空参数

信息

航空参数仅在航空支付场景下使用，其他交易类型无需传递。

参数名	类型	长度	是否必填	描述	示例
travel_totalTaxes	string	0-50	否	税费
travel_websiteLanguage	string	0-50	否	网站语言
travel_adult	string	0-3	否	成人数量
travel_child	string	0-3	否	子女数量
travel_infant	string	0-3	否	婴儿数量
travel_electronicTicket	string	1	是	是否为电子机票 1: True 0: False
travel_agencyCode	string	0-10	否	ATA机场代码
travel_pnr	string	1-10	是	PNR
travel_spnr	string	0-10	否	SPNR
ticket_deliveryMethod	string	1	是	票据的交付方式，仅支持小写字母 pick_up: 现场自取 email: 通过电子邮件发送 post: 通过邮寄发送 phone: 发送至手机号码
+travel_customerInfoJson	object	-	是	乘客节点信息（Json格式）

QuickPay

创建QuickPay ID

Note

当您在使用订阅场景，创建Quickpay ID时，此字段customer_id为必传。

参数名	类型	长度	是否必填	描述	示例
customer_id	string	1-50	是	用户ID 唯一值，商户用来区分不同用户	NO123456

发起扣款

Note

当您在使用订阅场景或快捷支付发起扣款时，此字段quickpay_id为必传。

参数名	类型	长度	是否必填	描述	示例
quickpay_id	string	1-200	是	Oceanpayment生成的唯一的Quickpay ID UUID格式	c6db7a28-7639-4d24-b7c5-6cd222c3e0fc

返回参数

浏览器同步返回：

• 每笔支付均以POST方式返回至交易传参的backUrl；
• 返回方式默认为POST，可修改为GET方式。

参数名	类型	描述	示例
response_type	string	回调类型 0：浏览器返回 1：服务器异步通知	0
account	string	账户号	995149
terminal	string	终端号	99514901
signValue	string	安全签名，用于验证交易的安全性，使用SHA256加密	A3F1C9D4E8B27F6A5C0D1E9F4B6A7C8D2E3F1A9B5C6D7E8F0A1B2C3D4E5F678
methods	string	支付方式	Credit Card
order_number	string	网站订单号	123456789
order_currency	string	订单号的交易币种	USD
order_amount	string	订单号的交易金额	1.00
order_notes	string	订单备注信息	test
card_number	string	持卡人的信用卡卡号	411111***1111
card_type	string	卡种	Visa
payment_country	string	消费者IP所在国家	US
payment_id	string	支付ID，Oceanpayment的支付唯一单号	26154125951032147852122
payment_status	string	该笔交易的结果状态 -1:待处理（预授权才会返回） 0:支付失败 1:支付成功	1
payment_authType	string	该笔交易的类型 0:该交易类型为‘Sale’一般交易 1:该交易类型为‘预授权且非3D’交易 2:该交易类型为‘3D且非预授权’交易 3:该交易类型为‘3D且预授权’交易	0
payment_details	string	该笔交易的支付详情 网站可以进行处理，在付款结果页面显示给消费者看	80000:Transaction Approved
payment_solutions	string	付款失败后的解决方法 网站可以进行处理，在付款结果页面显示给消费者看
payment_risk	string	未通过的风控规则 格式为：风控规则=分数;风控规则=分数;......
pay_barCode	string	订单打印码
payment_bankInfo	string	调起银行SDK的参数信息

异步通知

查看完整的Oceanpayment异步通知参数。