Debit/Credit Card Redirect API Documentation 版本号 : 语言 : 作者 : V1.0.0 简体中文 Pan
目录 深圳市钱海网络技术有限公司 A. 介绍... - 2 - A.1 版本说明... - 2 - B. 交易... - 3 - B.1 业务流程时序图... - 3 - B.2 提交地址... - 4 - B.3 请求参数... - 5 - B.4 示例代码 ( 注 : 必须用 form 表单提交参数 )... - 7 - B.5 交易响应... - 8 - B.6 流程图示... - 8 - B.7 响应代码... - 8 - B.8 服务器回调示例代码... - 10 - C. 附录... - 11 - C.1 常见交易币种 (ISO 4217)... - 11 - C.2 交易金额为正整数的币种列表... - 11 - C.3 支付页面语种... - 12 - C.4 sha256 加密方式示例... - 12 - - 1 -
A. 介绍 本文档是详细描述 Oceanpayment 信用卡支付网关的 API 接口文档 Oceanpayment 是一个专业处理国际信用卡 借记卡交易并同时提供 500 多种支付产品的支付方案解决商 本接口文档同时适用于商户以及合作伙伴, 基于 request-response 的模式, 简单易用 若有任何技术问题, 请邮件至 vergil@oceanpayment.com.cn A.1 版本说明 Oceanpayment 规定了 API 接口文档中说明准确的版本及日期, 以便于文档使用者可以区分不同版本的文档 该 API 是通过数字版本号进行版本命名 数字版本号由 3 部分组成, 第一部分表示主版本号, 所有大更新 重要更新都会影响主版本号 ; 第二部分表示主版本下的小更新 修复更新等, 一般不影响主要功能 ; 最后一部分为修订号, 一般是更新一些错误的拼写 错别字 错误的描述等 API 文档历史版本 : 版本号修订人描述日期 V1.0.0 Pan 初始版本 2018-01-01-2 -
B. 交易 B.1 业务流程时序图 - 3 -
业务流程说明 : (1) 消费者在网站下单 (2) 网站提交订单信息到 Oceanpayment 支付系统 (3)Oceanpayment 支付系统进行参数校验, 校验参数是否合法 (4)Oceanpayment 支付系统返回参数异常订单信息给网站 (5) 向用户展示订单结果 (6) 如果 (3) 校验通过, 向用户展示信用卡填写页面 (7) 消费者填写信用卡号等信息 (8)Oceanpayment 风控系统进行判断订单风险 (9)Oceanpayment 支付系统返回高风险订单信息给网站 (10) 向用户展示订单结果 (11) 如果 (8) 校验通过,Oceanpayment 支付系统将该笔订单扣款请求发送至银行 (12) 银行处理该笔付款请求, 返回支付结果 (13)Oceanpayment 支付系统返回支付结果给网站 (14)Oceanpayment 支付系统通过异步消息通知网站支付结果 (15) 网站响应 receive-ok 字符告知异步消息接收情况 (16) 未收到支付通知的情况下, 调用 Oceanpayment 对账 API 本文档错误! 未找到引用源 部分, 查询最新的订单状态 (17)Oceanpayment 对账 API 返回订单支付结果 (18) 向用户展示订单支付结果 (19) 如果支付成功则安排发货 B.2 提交地址 测试环境 :https://secure.oceanpayment.com/gateway/service/test 生产环境 :https://secure.oceanpayment.com/gateway/service/pay 注意事项 : ⑴: 发送请求的方式为 POST, 所有数据为 UTF-8 编码 ⑵: 该提交地址并非直接打开使用, 需将下表请求参数 POST 至该地址 - 4 -
⑶: 钱海账户分测试状态和正式状态, 测试状态只能提交到测试环境, 正式状态只能提交到生产环境 B.3 请求参数 注意事项 : ⑴: 测试环境中网站订单号只能支付提交 1 次, 不管是否付款成功, 生产环境中不存在该限制 ⑵: 如果交易金额为 0, 不需要发送至钱海支付系统 ⑶: 如果网站没有 billing 信息, 可用 shipping 信息代替 参数 类型 长度 必填 / 可选 说明 account String 6 必填 Oceanpayment 账户 terminal String 8 必填 账户号下的终端号 signvalue String 64 必填 交易安全签名, 用于验证交易的安全性 使用 SHA256 加密, 明文加密结构 : account+terminal+backurl+order_number+order_currency+order_am ount+billing_firstname+billing_lastname+billing_email+securecode backurl String 500 必填 返回支付信息的网站 URL 地址用于浏览器跳转 noticeurl String 500 可选 服务器回调 URL 地址, 用于交易结果推送及其他业务状态推送为了获取更准确订单状态, 此参数建议必传仅支持 80 及 443 端口收到服务器回调后需响应 receive-ok methods String 50 必填 支付方式, 值为 Credit Card 如果不填则默认支付方式为 Credit Card pages String 1 可选 影响持卡人看到的支付页面 0: PC 端页面 ( 默认 ) 1: 手机端页面 order_number String 50 必填 网站订单号 3 天时间内同一终端号下, 已经有成功或待处理的相同订单号下, 不能再次提交 order_currency String 3 必填 订单号的交易币种采用国际标准 ISO 4217, 请参考附录 order_amount String 10 必填 订单号的交易金额最大支持小数点后 2 位数, 如 :1.00 5.01 如果交易金额为 0, 不需要发送至钱海支付系统 order_notes String 500 可选 订单备注信息, 返回时则原样返回 billing_firstname String 50 必填 消费者的名如果没有该值必须传 : 消费者 id 或 N/A 传值时须去首尾空格, 对特殊字符 ( < >) 进行转义, 否则会影响 signvalue 校验 - 5 -
billing_lastname String 50 必填 billing_email String 50 必填 billing_phone String 50 必填 billing_country String 100 必填 billing_state String 100 可选 billing_city String 100 必填 billing_address String 500 必填 billing_zip String 50 必填 ship_firstname String 50 可选 ship_lastname String 50 可选 ship_phone String 50 可选 ship_country String 100 可选 ship_state String 100 可选 ship_city String 100 可选 ship_addr String 500 可选 ship_zip String 50 可选 productsku String 500 可选 消费者的姓如果没有该值必须传 : 消费者 id 或 N/A 传值时须去首尾空格, 对特殊字符 ( < >) 进行转义, 否则会影响 signvalue 校验消费者的邮箱如果没有该值可默认传 : 消费者 id@ 域名或简称.com 传值时须去首尾空格, 对特殊字符 ( < >) 进行转义, 否则会影响 signvalue 校验消费者的电话如果没有该值必须传 :N/A 消费者的账单国家采用国际标准 ISO 3166 代码, 如 : 美国 US 如果没有该值必须传 : N/A 如果采用的是非国际标准 ISO 3166 代码, 会影响系统的风控判断消费者的州 ( 省 郡 ), 如果没有该值可传 :N/A 消费者的城市如果没有该值必须传 :N/A 消费者的详细地址如果没有该值必须传 :N/A 消费者的邮编如果没有该值必须传 :N/A 收货人的名如果没有该值可传 :N/A 收货人的姓如果没有该值可传 :N/A 收货人的电话如果没有该值可传 :N/A 收货人的国家采用国际标准 ISO 3166 代码, 如 : 美国 US 如果采用的是非国际标准 ISO 3166 代码, 会影响系统的风控判断如果没有该值可传 :N/A 收货人的州 ( 省 郡 ) 如果没有该值可传 :N/A 收货人的城市如果没有该值可传 :N/A 收货人的详细地址如果没有该值可传 :N/A 收货人的邮编如果没有该值可传 :N/A 产品 SKU 多个产品用 ; 隔开如果没有该值可传 :N/A - 6 -
productname String 500 可选 productnum String 50 可选 cart_info String 50 可选 cart_api String 50 可选 logourl String 500 可选 language String 8 可选 产品名称多个产品用 ; 隔开如果没有该值可传 :N/A 产品数量多个产品用 ; 隔开如果没有该值可传 :N/A 设备终端类型如 PC Wap Android ios Oceanpayment API 接口版本本接口版本为 V1.8.4 用于显示在支付页面上的 logo URL 仅在部分支付页面样式中生效支付页面显示语言默认根据浏览器语言进行适配, 支持 9 种语言, 默认英语 (en_us) 语言清单参考附录 C.2, 如果传入值非附录中的值, 默认显示英语 B.4 示例代码 ( 注 : 必须用 form 表单提交参数 ) 注意事项 : 下列代码仅提供提交模式参考, 不能直接复制后提交 <form action= https://secure.oceanpayment.com/gateway/service/test method="post" > <input type="hidden" name="account" value="140105" /> <input type="hidden" name="terminal" value="14010501" /> <input type="hidden" name="order_number" value="20123456789" /> <input type="hidden" name="order_currency" value="usd" /> <input type="hidden" name="order_amount" value="100.00" /> <input type="hidden" name="signvalue" value="egh4fjs2f3h4mc5g3j7676vzva53gfd33dfga1458fe2f12343y" /> <input type="hidden" name="backurl" value="http://www.abc.com/result.php" /> <input type="hidden" name="noticeurl" value="http://www.abc.com/notice.php" /> <input type="hidden" name="billing_firstname" value="test" /> <input type="hidden" name="billing_lastname" value="test" /> <input type="hidden" name="billing_email" value="test@test.com" /> <input type="hidden" name="billing_phone" value="0755-123456789" /> <input type="hidden" name="methods" value="credit Card" /> <input type="hidden" name="billing_country" value="us" /> <input type="hidden" name="billing_city" value="washington D.C." /> <input type="hidden" name="billing_address" value="705a big Road" /> <input type="hidden" name="billing_zip" value="529012" /> <input type="hidden" name="productsku" value="#001" /> <input type="hidden" name="productname" value="dress" /> <input type="hidden" name="productnum" value="1" /> </form> - 7 -
B.5 交易响应 服务器回调 ( 异步通知 ): 是服务器到服务器的数据回调 浏览器回调 : 通过浏览器重定向的数据回调 B.6 流程图示 说明 : 1 发送交易请求 2 发送扣款请求 3 付款完成, 数据返回 4 浏览器回调, 数据返回 ( 返回依赖于 backurl) 5 服务器回调, 数据返回 ( 返回依赖于 noticeurl, 如果没有 noticeurl 则回调至 backurl) 注意事项 : ⑴: 服务器回调默认启用, 如需关闭请联系 Oceanpayment 技术支持人员 ⑵:45 将同时进行 ⑶: 服务器回调格式为 xml ⑷: 启用 CDN 可能会影响接收服务器回调 ⑸: 收到服务器回调后需响应 receive-ok B.7 响应代码 注意事项 : ⑴: 服务器回调格式为 xml,response_type 为 1 ⑵: 浏览器回调格式为表单 POST,response_type 为 0 ⑶: 其余字段保持一致 - 8 -
参数 类型 说明 response_type String 回调类型 0: 浏览器回调 1: 服务器回调 account String Oceanpayment 账户 terminal String 账户号下的终端号 signvalue String 交易安全签名, 用于验证交易的安全性 使用 SHA256 加密, 明文加密结构 : account+terminal+order_number+order_currency+order_amount+order_notes+car d_number+payment_id+payment_authtype+payment_status+payment_details+pa yment_risk+securecode 请注意大小写 methods String 支付方式 order_number String 网站订单号 3 天时间内同一终端号下, 已经有成功或待处理的相同订单号下, 不能再次提交 order_currency String 订单号的交易币种采用国际标准 ISO 4217, 请参考附录 order_amount String 订单号的交易金额最大支持小数点后 2 位数, 如 :1.00 5.01 如果交易金额为 0, 不需要发送至钱海支付系统 order_notes String 订单备注信息, 原样返回 card_number String 持卡人的信用卡卡号, 截取前 6 位和后 4 位如 :436745***1719 payment_id String 支付 ID,Oceanpayment 的支付唯一单号 payment_country String 消费者所在国家如 :US payment_authtype String 该笔交易的类型 0: 消费交易 1: 预授权交易 payment_status String 该笔交易的结果状态 -1: 待处理 ( 预授权才会有 ) 0: 失败 1: 成功 payment_details String 该笔交易的支付详情, 格式为 :Code + : + Descrition 如 :80000:Transaction Approved 10000:High risk 网站可以进行处理, 在付款结果页面显示 Descrition, 不需要展示 Code 给消费者看 payment_risk String 未通过的风控规则, 格式为 : 风控规则 = 分数 ; 风控规则 = 分数 ;... 如 :sourceurl=100.0(http://www.abc.com); payment_solutions auth_reason String String 付款失败后的解决方法如 :1. Try to Pay again.2. Call the... 网站可以进行处理, 在付款结果页面显示给消费者看 预授权操作原因仅限于账户后台操作 ( 服务器回调 ) 进行返回, 通过预授权 API 操作则不返回该字段 - 9 -
order_operator String 账户后台预授权交易处理操作人 返回账户后台操作人的登录名 () 仅限于账户后台操作 ( 服务器回调 ) 进行返回, 通过预授权 API 操作则不返回该字段 B.8 服务器回调示例代码 <?xml version='1.0' encoding='utf-8'?> <response> <response_type>1</response_type> <account>140105</account> <terminal>14010508</terminal> <signvalue>4b9aaa1ad0b931d46d46842227c62776ebf270b8c73be0fd9c65b7f22852e74a</signvalue> <methods>credit Card</methods> <order_number>500000102</order_number> <order_currency>usd</order_currency> <order_amount>156.03</order_amount> <order_notes></order_notes> <card_number>436745******1719</card_number> <payment_country>us</payment_country> <payment_id>150417134644140105991</payment_id> <payment_authtype>0</payment_authtype> <payment_status>0</payment_status> <payment_details>80036:transaction Not Allowed</payment_details> <payment_risk>sourceurl=10.0(http://www.abc.com);</payment_risk> <payment_solutions>1. Try to Pay again.2. Call the...</payment_solutions> <auth_reason >test</ auth_reason> <order_operator>admin</order_operator> </response> - 10 -
C. 附录 C.1 常见交易币种 (ISO 4217) 币种名 代码 币种名 代码 Won KRW Russian Ruble RUB Yeni Türk Liras TRY Convertible Marks BAM Rand ZAR Bulgarian Lev BGN UAE Dirham AED Croatian Kuna HRK Mexican Peso MXN Forint HUF Chilean Peso CLP Lithuanian Litas LTL Belarussian Ruble BYR Latvian Lats LVL Malaysian Ringgit MYR Leu romacircnesc RON Denar MKD Serbian dinars RSD Serbian Dinar CSD Brazilian Real BRL Pakistan Rupee PKR Baht THB Hryvnia UAH New Israeli Sheqel ILS Iranian Rial IRR Yuan Renminbi CNY Tanzanian Shilling TZS US Dollar USD Armenian Dram AMD Pound Sterling GBP Iceland Krona ISK Euro EUR Azerbaijan Manat AZN Australian Dollar AUD Lek ALL Canadian Dollar CAD Taka BDT Yen JPY Saudi Riyal SAR Singapore Dollar SGD Lari GEL Hong Kong Dollar HKD Zloty PLN Malaysian Ringgit MYR New Zealand Dollar NZD Philippine Peso PHP Norvegian Krone NOK New Taiwan Dollar TWD Danish Krone DKK Indian Rupee INR Swedish Krona SEK Czech Koruna CZK Swiss Franc CHF Vietnamese Dong VND C.2 交易金额为正整数的币种列表 币种 BIF BYR CLP - 11 - 国家 Burundian franc Belarusian ruble Chilean peso
CVE DJF GNF ISK JPY KMF KRW PYG RWF UGX UYI VND VUV XAF XOF XPF Cape Verde escudo Djiboutian franc Guinean franc Icelandic króna Japanese yen Comoro franc South Korean won Paraguayan guaraní Rwandan franc Ugandan shilling Uruguay Peso en Unidades Indexadas Vietnamese dong Vanuatu vatu CFA franc BEAC CFA franc BCEAO CFP franc (franc Pacifique) C.3 支付页面语种 语种英语德语法语意大利语西班牙语葡萄牙语俄语日语韩语阿拉伯语 代码 en_us de;de_de;de_at;de_li;de_lu;de_ch fr;fr_fr;fr_be;fr_ca;fr_lu;fr_mc;fr_ch it;it_it;it_ch es;es_es;es_ar;es_py;es_pa;es_pr;es_bo;es_es_tradnl;es_do;es_ec;es_co; es_cr;es_hn;es_pe;es_mx;es_ni;es_sv;es_gt;es_ve;es_uy;es_cl pt;pt_pt;pt_br ru;ru_ru;ru_md ja;ja_jp ko;ko_kr ar;ar_sa C.4 sha256 加密方式示例 注意事项 : ⑴ 若提交参数中带有 < > 请将 html 转码之后再进行加密 Java 加密方式 ( 仅做参考 ) signvalue=sha256(account+terminal+backurl+order_number+order_currency+order_amount+billing_firstname+b illing_lastname+billing_email+securecode); - 12 -
PHP 加密方式 ( 仅做参考 ) $signvalue=hash("sha256",$account.$terminal.$backurl.$order_number.$order_currency.$order_amount.$billing _firstname.$billing_lastname.$billing_email.$securecode); - 13 -