概述
本文档介绍如何将 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。
- Response
//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。
- Request
{
"data": "",
"signature": "",
"header": {
"publicKeyHash": "",
"ephemeralPublicKey": "",
"transactionId": ""
},
"version": "EC_v1"
}
注意
pay_accountNumber必须完整保留 Apple 返回的paymentData对象内容;- Payment Token 获取后应立即提交支付请求,避免 Token 过期;
- 当前支持 Apple Pay 返回的 EC_v1加密格式。
7. card_type 传参说明
card_type用于传递 Apple Pay Payment Token 中的paymentMethod.network,商户需将paymentMethod.network返回值转换为 Oceanpayment card_type支持的枚举值后进行传输。
paymentMethod.network | card_type |
|---|---|
| visa | VISA |
| masterCard | MASTERCARD |
| maestro | MAESTRO |
| JCB | JCB |
| elo | ELO |
| discover | DISCOVER |
| chinaUnionPay | CHINAUNIONPAY |
| cartesBancaires | CARTESBANCAIRES |
| amex | AMEX |
- Request
-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":"MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgAYJKoZIhvcNAQcBAACggDCCA+MwggOIoAMCAQICCBZjTIsOMFcXMAoGCCqGSM49BAMCMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0yNDA0MjkxNzQ3MjdaFw0yOTA0MjgxNzQ3MjZaMF8xJTAjBgNVBAMMHGVjYy1zbXAtYnJva2VyLXNpZ25fVUM0LVBST0QxFDASBgNVBAsMC2lPUyBTeXN0ZW1zMRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABMIVd+3r1seyIY9o3XCQoSGNx7C9bywoPYRgldlK9KVBG4NCDtgR80B+gzMfHFTD9+syINa61dTv9JKJiT58DxOjggIRMIICDTAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFCPyScRPk+TvJ+bE9ihsP6K7/S5LMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMB0GA1UdDgQWBBSUV9tv1XSBhomJdi9+V4UH55tYJDAOBgNVHQ8BAf8EBAMCB4AwDwYJKoZIhvdjZAYdBAIFADAKBggqhkjOPQQDAgNJADBGAiEAxvAjyyYUuzA4iKFimD4ak/EFb1D6eM25ukyiQcwU4l4CIQC+PNDf0WJH9klEdTgOnUTCKKEIkKOh3HJLi0y4iJgYvDCCAu4wggJ1oAMCAQICCEltL786mNqXMAoGCCqGSM49BAMCMGcxGzAZBgNVBAMMEkFwcGxlIFJvb3QgQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDUwNjIzNDYzMFoXDTI5MDUwNjIzNDYzMFowejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8BcRhBnXZIXVGl4lgQd26ICi7957rk3gjfxLk+EzVtVmWzWuItCXdg0iTnu6CP12F86Iy3a7ZnC+yOgphP9URaOB9zCB9DBGBggrBgEFBQcBAQQ6MDgwNgYIKwYBBQUHMAGGKmh0dHA6Ly9vY3NwLmFwcGxlLmNvbS9vY3NwMDQtYXBwbGVyb290Y2FnMzAdBgNVHQ4EFgQUI/JJxE+T5O8n5sT2KGw/orv9LkswDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBS7sN6hWDOImqSKmd6+veuv2sskqzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXJvb3RjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEAYKKoZIhvdjZAYCDgQCBQAwCgYIKoZIzj0EAwIDZwAwZAIwOs9yg1EWmbGG+zXDVspiv/QX7dkPdU2ijr7xnIFeQreJ+Jj3m1mfmNVBDY+d6cL+AjAyLdVEIbCjBXdsXfM4O5Bn/Rd8LCFtlk/GcmmCEm9U+Hp9G5nLmwmJIWEGmQ8Jkh0AADGCAYgwggGEAgEBMIGGMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUwIIFmNMiw4wVxcwCwYJYIZIAWUDBAIBoIGTMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTI2MDQyODAxMjAzNFowKAYJKoZIhvcNAQk0MRswGTALBglghkgBZQMEAgGhCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIIK4+XtpMfs8dNhIcHN1yfhKpPbPl51/szvsVGeyJ/OeMAoGCCqGSM49BAMCBEcwRQIhALrohlHhqUHhI3f7CQW0NKBuEtrq2djbsfdjC1mkURIeAiAG8xxmOZzm0fFAQ5Ldp2pP4at0oDICtmQfiYxagb5FCwAAAAAAAA==","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 直连接口创建订阅快捷支付。
响应
- 从支付返回结果中获取
pay_url字段,并据此判断是否需要进行 3D 验证。查看完整的响应参数。
- Response
<?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接收交易的异步通知。
签名
查看详细的签名和验签功能。