跳到主要内容

概述​

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

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

开始之前​

使用 Apple Pay 服务器对服务器集成时,商户需要注册 Apple Pay 官方开发者账号,调用 Payment Token 流程获取卡信息 Token,再将该 Token 作为参数传递给 Oceanpayment。

流程图​

请求​

1. 注册 Apple Developer​

访问 https://developer.apple.com, 加入 Apple Developer Program。

2. 创建 Merchant ID​

  • 登录 Apple Developer → Certificates, Identifiers & Profiles;
  • 点击左侧菜单 Identifiers → Merchant IDs → (+),创建 Merchant ID。示例:merchant.com.example.store

3. 创建 Payment Processing Certificate(支付处理证书)​

  • 在 Mac 上使用 Keychain 或 OpenSSL 生成 CSR(Certificate Signing Request);
  • 登录 Apple Developer → Certificates;
  • 选择 Payment Processing Certificate 类型创建证书;
  • 上传 CSR,Apple 返回 .cer文件;
  • 下载并安装证书到本地 Keychain;
  • 从 Keychain 导出.p12文件(包含私钥);
    .p12文件用于服务器端解密 Apple Pay 返回的 Payment Token。

4. 配置 Merchant Domain 白名单​

  • 登录 Apple Developer → Merchant IDs → Domain Verification;
  • 添加商户域名(如 example.com,www.example.com);
  • 按提示下载验证文件 apple-developer-merchantid-domain-association.txt,在生成后必须在7天内完成部署与点击验证,否则该文件会过期,需要重新生成;
  • 上传到网站根目录,如:https://example.com/.well-known/apple-developer-merchantid-domain-association.txt
  • 点击 Verify 完成验证。

5. 获取 Payment Token​

请参考 Apple Pay 官方示例获取 Payment Token。

//Payment Token 示例
{
"paymentData": {
"data": "",
"signature": "",
"header": {
"publicKeyHash": "",
"ephemeralPublicKey": "",
"transactionId": ""
},
"version": "EC_v1"
},
"paymentMethod": {
"displayName": "Visa 0112",
"network": "Visa",
"type": "credit"
},
"transactionIdentifier": ""
}

6. Payment Token 传参说明​

  • 发起 Oceanpayment 支付请求时,pay_accountNumber用于传递 Apple Pay Payment Token 中的paymentData对象。
  • 传值规则:请将以下节点完整传递至pay_accountNumber。
{
"data": "",
"signature": "",
"header": {
"publicKeyHash": "",
"ephemeralPublicKey": "",
"transactionId": ""
},
"version": "EC_v1"
}
注意
  1. pay_accountNumber必须完整保留 Apple 返回的paymentData对象内容;
  2. Payment Token 获取后应立即提交支付请求,避免 Token 过期;
  3. 当前支持 Apple Pay 返回的 EC_v1加密格式。

7. card_type 传参说明​

card_type用于传递 Apple Pay Payment Token 中的paymentMethod.network,商户需将paymentMethod.network返回值转换为 Oceanpayment card_type支持的枚举值后进行传输。

paymentMethod.networkcard_type
visaVISA
masterCardMASTERCARD
maestroMAESTRO
JCBJCB
eloELO
discoverDISCOVER
chinaUnionPayCHINAUNIONPAY
cartesBancairesCARTESBANCAIRES
amexAMEX
-d 'card_type=VISA' \

8. 发起支付请求​

商户服务器通过直连模式调用提交必要参数,并将 Apple Pay 返回的卡信息 Token 作为 pay_accountNumber 参数传入。

cURL -X POST 'https://test-secure.oceanpayment.com/gateway/direct/pay'
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'account=995149' \
-d 'terminal=99514901' \
-d 'signValue=6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b' \
-d 'backUrl=https://www.abc.com/back.php' \
-d 'noticeUrl=https://www.abc.com/notice.php' \
-d 'order_number=NO12345678' \
-d 'order_currency=USD' \
-d 'order_amount=0.01' \
-d 'methods=ApplePay' \
-d 'order_notes=' \
-d 'pay_accountNumber={"data":"ned7UHi3Uti0VPrayQVZ7lIEBBeahdv02bFf65k4xVNzoMCm1ansTK+dbeoCb5doLRIm7FWYjJOmUE2/HMARrDShl0fNWn5V+2sX6WhhY7RwV13XD5BFJ3bqb8LvuzeWhX2ILKfQ9n3KqGXrTQC8M+YrbHS0eQZXBFBSlNeebn+izrbSzk+xmxBXGrK1R8/ov7q+i5/1q64+a0Eh1QGscBbweOuvBOsJl1CSSYvoRXF3GTHO1c80fGE1GWtHBPjDmhtjl7Al57lZPBenfnA/PXCx1NeUQPJcfNIXY/Ax9q2GjVk2nfXyGepvB8cXpdYZ7gqCo6V13B28D7qX3/AJo1CWEeH8ulVNbRu2sJKoE5/vIOmXXmUJY/2gwCQOnebXxtLjGlOJO8DiOAFDEdQx6pGpi9Ckzi8S7IU294s=","signature":"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","header":{"publicKeyHash":"sLiXc1clhfuSZN/HBtYjdW81oXfXcqdRXsd6nB3Rua8=","ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEAKwAnvO9+06yugF6pninfzLfwNOyHvKDdOM+MweabfSU1GjG3fN9tLc6mvz1g1RGuIQrrqhfb2MCSzBGcY7R2Q==","transactionId":"627f630d5f403f676697ee779752abe338e9a05e8ba92b111bb69dd1f43cbb15"},"version":"EC_v1"}' \
-d 'card_type=VISA' \
-d 'billing_firstName=test' \
-d 'billing_lastName=test' \
-d 'billing_email=test@gmail.com' \
-d 'billing_phone=13800138000' \
-d 'billing_country=US' \
-d 'billing_state=AL' \
-d 'billing_city=Washington D.C.' \
-d 'billing_address=705A big Road' \
-d 'billing_zip=529012' \
-d 'billing_ip=127.0.0.1' \
-d 'productNum=1' \
-d 'productName=Red Dress' \
-d 'productSku=#001' \
-d 'productPrice=0.01' \

快捷支付​

将 Payment Token 作为 pay_accountNumber 参数传递给 Oceanpayment,即可通过 QuickPay 直连接口创建订阅快捷支付。

响应​

  1. 从支付返回结果中获取 pay_url 字段,并据此判断是否需要进行 3D 验证。查看完整的响应参数。
<?xml version="1.0" encoding="UTF-8"?>
<response>
<notice_type>transaction</notice_type>
<push_dateTime>2025-12-19 09:52:47</push_dateTime>
<account>995149</account>
<terminal>99514901</terminal>
<signValue>D6315600AE0002C1468DC9B943E17E90B314E73581393ABC332B92985E41B100</signValue>
<methods>ApplePay</methods>
<order_number>NO12345678</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>231219095247018026021</payment_id>
<payment_authType>3</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></pay_url>
</response>
  • 如果 xml->pay_url字段为空,无3D 验证环节,则 xml 就是返回的支付结果。此时会触发 noticeUrl异步通知。
  • 如果 xml->pay_url字段不为空,有3D 验证环节,需要重定向打开pay_url完成3D 校验,此时支付返回结果会再次发送至backUrl,默认用$_POST 接收返回。此时也会触发noticeUrl异步通知。
    • 商户将用户重定向到pay_url :
HTTP/1.2 301 Moved Permanently
Location: {pay_url}

付款状态​

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

异步通知​

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

签名​

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