跳到主要内容

概述​

本文档介绍如何将信用卡通过嵌入式接入 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. 返回示例​

<?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}

付款状态​

查看详细的付款状态说明。

异步通知​

您还需要通过noticeUrl接收交易的异步通知。

签名​

查看详细的签名和验签功能。