概述
本文档介绍如何将信用卡通过嵌入式接入 Oceanpayment,包括支付参数提交、交易处理及结果返回,帮助商户快速了解整体对接流程。
如需使用其他方案接入信用卡,请参阅信用卡接入文档。
流程图
请求
1. 加载 Oceanpayment SDK
//加载 Oceanpayment Js 文件
<script src="https://secure.oceanpayment.com/pages/js/oceanpayment.js"></script>
//加载 Jquery
<script src="https://secure.oceanpayment.com/pub/js/jquery/jq.js"></script>
2. 创建容器
//加载 Oceanpayment 支付页面
<div id="oceanpayment-element"></div>
3. 初始化
使用初始化并渲染支付 UI 组件到容器中,初始化init();
- 传值
true提交沙盒环境; - 传空提交生产环境。
<script>
$(function() {
var configuration = {"showCardName": true};
//传 true 提交沙盒环境,传空提交生产环境
Oceanpayment.init(true,'','',configuration);
});
</script>
4. 自定义样式
您可以通过在线的 CSS 样式文件,用来覆盖 Oceanpayment 支付页面原有的样式,达到修改样式的效果,cssUrl初始化时默认为空。
<script>
$(function() {
var configuration = {"showCardName": true};
//CSS URL 地址
Oceanpayment.init(true,'https://example.com/css/style.css','',configuration);
});
</script>
5. 自定义支付语言
支付页面会根据设备语言进行适配,您也可以通过传值进行自定义,支持24种支付语言,默认英语(en_US)。
<script>
$(function() {
var configuration = {"showCardName": true};
//语言代码
Oceanpayment.init(true,'https://example.com/css/style.css','en_US',configuration);
});
</script>
6. 提交支付
- 调用支付方法,支付时需要做防重复提交处理;
- 使用方法
transformToJson(formData){}将提交的必填参数转为Json格式; - 再调用
checkout()提交必要参数给 Oceanpayment 支付网关。
//提交参数
<script>
//支付方法
function pay() {
//获取 form 表单元素
var register = $("#payForm");
//Jquery 的 serialize()方法
var formData = register.serializeArray();
//提交参数信息给 Oceanpayment 支付网关
Oceanpayment.checkout(transformToJson(formData));
}
//输出 Json 数据
function transformToJson(formData){
var obj={}
for (var i in formData) {
obj[formData[i].name]=formData[i]['value'];
}
return obj;
}
</script>
快捷支付
您也可以调用 QuickPay 嵌入式接口创建订阅,实现快捷支付。
响应
1. 监听
前端监听支付结果事件,查看完整的响应参数。
注意
Oceanpayment 将支付返回结果发送至backUrl页面,backUrl 传值一定要和当前页面的地址和完整路径完全一致,才能调用CallBack()方法接收支付返回信息。
var oceanpaymentCallBack = function(data){}
2. 校验
当卡信息校验失败时,data.msg会返回报错信息,例如:
//卡号输入错误
{"code":-1, "msg":"Your credit card number is incorrect."}
3. 3D 场景
当data.msg返回为空时,表示卡信息校验通过。在else中接收支付返回,判断以下两个场景:
- 如果 xml->
pay_url字段为空,无3D 验证环节,则 xml 就是返回的支付结果。此时也会触发noticeUrl异步通知。 - 如果 xml->
pay_url字段不为空,有3D 验证环节,需要重定向打开 pay_url 完成3D 校验,此时支付返回结果会再次发送至backUrl,默认用$_POST 接收返回。此时也会触发 noticeUrl 异步通知。
var oceanpaymentCallBack = function(data){
if(data.msg){
//处理卡信息错误
console.log(data.msg);
}else{
//处理下单返回
//没有报错时,接收 backUrl 返回,解析返回 xml
console.log(data);
}
}
4. 返回示例
- 3D 场景
- 非3D 场景
<?xml version="1.0" encoding="UTF-8"?>
<response>
<notice_type>transaction</notice_type>
<push_dateTime>2025-09-03 10:21:14</push_dateTime>
<account>995149</account>
<terminal>99514901</terminal>
<signValue>924347D8E9C9BAC2EC91449C70540FF49E0DD5711F03E8A871DCA34CED023AB6</signValue>
<methods>Credit Card</methods>
<order_number>JSCSE-3128790866</order_number>
<card_country>PL</card_country>
<order_currency>USD</order_currency>
<order_amount>0.01</order_amount>
<order_notes></order_notes>
<card_number>411111***1111</card_number>
<card_type>Visa</card_type>
<payment_country></payment_country>
<payment_id>250902111334242179639</payment_id>
<payment_authType>2</payment_authType>
<payment_status>-1</payment_status>
<payment_details>80093:3D Authorized Service not completed</payment_details>
<payment_solutions></payment_solutions>
<payment_risk></payment_risk>
<payment_amount></payment_amount>
<payment_exchangeRate></payment_exchangeRate>
<auth_reason></auth_reason>
<auth_code></auth_code>
<pay_userId></pay_userId>
<pay_url>https://secure.oceanpayment.com:443/gateway/direct/redirect?pay_id=af5e28ee57061f4fd1dd307a7bc56c7289d9041d0b5494195d91b7c5166b6e30</pay_url>
</response>
- 商户将用户重定向到
pay_url:
HTTP/1.2 301 Moved Permanently
Location: {pay_url}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<notice_type>transaction</notice_type>
<push_dateTime>2025-09-03 10:21:14</push_dateTime>
<account>995149</account>
<terminal>99514901</terminal>
<signValue>6E48108837603DF6758BD6CE81C9F8AEE6FDC40D14D056C41EBCC1B28B1F2A0D</signValue>
<methods>Credit Card</methods>
<order_number>JSCSE-3128790866</order_number>
<card_country>PL</card_country>
<order_currency>USD</order_currency>
<order_amount>0.01</order_amount>
<order_notes></order_notes>
<card_number>411111***1111</card_number>
<card_type>Visa</card_type>
<payment_country>-</payment_country>
<payment_id>250903102114589130422</payment_id>
<payment_authType>0</payment_authType>
<payment_status>1</payment_status>
<payment_details>80000:Transaction Approved</payment_details>
<payment_solutions>None required.</payment_solutions>
<payment_risk></payment_risk>
<payment_amount></payment_amount>
<payment_exchangeRate></payment_exchangeRate>
<auth_code></auth_code>
<pay_userId></pay_userId>
</response>
付款状态
查看详细的付款状态说明。
异步通知
您还需要通过noticeUrl接收交易的异步通知。
签名
查看详细的签名和验签功能。