跳到主要内容

概述​

本文档介绍如何将 Apple Pay 通过服务器直连接入 Oceanpayment,包括支付参数提交、交易处理及结果返回,帮助商户快速了解整体对接流程。

如需使用其他方案接入 Apple Pay,请参阅 Apple Pay 接入文档。

流程图​

开始之前​

信息

Apple Pay 使用嵌入式集成时,商户必须先为其注册的每个域名添加 Oceanpayment 托管域名验证文件。

1. 域名验证文件部署​

商户需在所有使用 Apple Pay 的网站域名下部署 Apple 官方域名验证文件,并确保此路径文件可以正常访问: ⬇️ 点击下载域名验证文件

https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association

每个独立域名和子域名都需要部署验证文件。

https://example.com/.well-known/apple-developer-merchantid-domain-association
https://test.example.com/.well-known/apple-developer-merchantid-domain-association
···

2. 发起域名注册​

  • 完成验证文件部署后,调用 Oceanpayment 域名注册接口:
cURL -X POST 'https://mds.oceanpayment.com/appleregistermerchant'
-H 'Authorization: MVc9Lt1CDY7RBRUvh8iVmvvPbYF3uvWkymUDz'
-d '{
"website": ["example.com","test.example.com"]
}'
参数类型必填说明
websiteArray是需要注册的域名列表
  • 错误处理
响应码说明
200OK
  • Success.
400Bad Request
  • The request is malformed or invalid.
401Unauthorized
  • The request is malformed or invalid.
417Expectation Failed
  • The e-commerce platform isn’t registered with Apple Developer.
500Internal Server Error
  • An internal server error occurred.

3. 集成​

完成域名校验后,结账页面将在可能的情况下显示 Apple Pay 作为付款选项。

注意

嵌入式集成 Apple Pay 仅适用于支持它的 Apple 设备(例如 Safari 网页浏览器、iOS 设备),且支付按钮仅在 iOS 17及以上版本才会显示。

请求​

1. 加载 Oceanpayment SDK​

//加载 Oceanpayment Js 文件
<script src="https://secure.oceanpayment.com/pages/js/oceanpayment-applepay.js"></script>
//加载 Jquery
<script src="https://secure.oceanpayment.com/pub/js/jquery/jq.js"></script>

2. 创建容器​

//加载 Apple Pay 支付按钮
<div id="oceanpayment-applepayelement"></div>

3. 初始化​

使用初始化并渲染支付 UI 组件到容器中,初始化init();

  • 传值true提交沙盒环境;
  • 传空提交生产环境;
  • billCountry:店铺注册国家/地区代码,ISO 3166格式。
//初始化 Oceanpayment
<script>
$(function() {
//传 true 提交沙盒环境,传空提交生产环境。
onePageApplePay.init(true, {
terminal: '99514901', /*Oceanpayment 终端号*/
transactionInfo: {
//*传入订单实际的金额,币种
orderCurrency: ORDER_CURRENCY,/*交易币种*/
orderAmount: ORDER_AMOUNT,/*交易金额*/
billCountry: BILLING_COUNTRY,/*店铺注册国家/地区代码*/
orderNumber: ORDER_NUMBER,/*订单号*/
billAddress: BILLING_ADDRESS /*账单地址*/
},

});
});
</script>

4. 自定义样式​

您可以通过在线的 CSS 样式文件,用来覆盖 Oceanpayment 支付页面原有的样式,达到修改样式的效果,cssUrl初始化时默认为空。

//初始化 Oceanpayment
<script>
$(function() {
//传 true 提交沙盒环境,传空提交生产环境。
onePageApplePay.init(true, {
cssUrl: '',/*传入线上 css 样式文件地址,可以控制按钮大小*/
buttonStyle: {
buttonstyle:'', /*按钮颜色*/
type:'' /*按钮类型*/
}
});
});
</script>

5. 更新订单金额、币种​

当订单金额、币种发生变化时,例如商品价格、折扣、税费或运费发生变化,商户可以调用此方法更新订单交易信息。

<script>
function updateTransactionInfo() {
onePageApplePay.updateTransactionInfo({
transactionInfo: {
orderCurrency: ORDER_CURRENCY, //币种
orderAmount: ORDER_AMOUNT //金额
}
});
}
</script>

6. 唤起 Apple Pay 支付弹窗​

  • 商户可通过调用onePageApplePay.validateResults()方法控制 Apple Pay 支付弹窗的唤起。请在 Apple Pay 初始化完成后,根据网站自身的表单校验结果,在适当的时机调用该方法。
    • 如果网站账单信息等必填项校验未通过,请调用 onePageApplePay.validateResults(false),阻止唤起支付弹窗。
    • 当必填项校验通过后,再调用 onePageApplePay.validateResults(true) 唤起支付弹窗。
<script>
function validateResults() {
onePageApplePay.validateResults(true);
}
</script>

7. 提交支付​

  • 调用支付方法,支付时需要做防重复提交处理;
  • 使用方法transformToJson(formData){}将提交的必填参数转为Json格式;
  • 再调用checkout()提交必要参数给 Oceanpayment 支付网关。
//提交参数
<script>
//Oceanpayment 支付方法
function opApplepay() {
//获取 form 表单元素
var register = $("#payForm");
//Jquery 的 serialize()方法
var formData = register.serializeArray();
//提交参数信息给 Oceanpayment 支付网关
onePageApplePay.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 oceanpaymentApplePayCallBack = function(data){}

2. 校验​

当data.code = 3,表示用户关闭了 Apple Pay 支付弹窗,数据返回格式:

{"code":3,"msg":"","method":"ApplePay"}

3. 3D 场景​

当data.code = 2,表示 Apple Pay 按钮加载成功。在else中接收支付返回,判断以下两个场景:

  • 如果 xml->pay_url字段为空,则 xml 就是返回的支付结果。此时也会触发noticeUrl异步通知。
  • 如果 xml->pay_url字段不为空,则需要重定向打开 pay_url 完成3D 校验,此时支付返回结果会再次发送至backUrl,默认用$_POST 接收返回。此时也会触发 noticeUrl 异步通知。
var oceanpaymentApplePayCallBack = function(data){
if (data.code == 2) {
//唤起按钮,调用支付
opApplepay();
}else{
/*处理下单返回*/
//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>Applepay</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接收交易的异步通知。

签名​

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