- 集成指南
- 支持的功能（付款方式）
- 设备付款
- Apple Pay 支付
Apple Pay
Apple Pay 是 Apple Inc. 提供的一项移动支付和数字钱包服务，允许付款人使用支持的 iOS 和 macOS 设备进行付款。 Apple Pay 是 Mastercard Gateway 支持的设备付款。
此页内容介绍特定于 Apple Pay 的集成详细信息。 建议您在构建 Apple Pay 集成前，先阅读设备付款集成指南。
先决条件
若要接受 Apple Pay 付款：
- 您必须在 Apple 注册并创建商家 ID。
- 您在网关上的商家配置文件必须由 your payment service provider 启用设备付款。
- 如果您希望网关执行付款令牌解密，您在网关上的商家配置文件必须具有“启用 Apple Pay 设备付款解密”权限。
在您的集成中添加对 Apple Pay 的支持
您可以使用 Direct Payment 将 Apple Pay 集成到您的移动应用内或您网站的结账页。
DirectAPI 版本 46 之前的版本提供对解密 Apple Pay 付款令牌的网关支持。
- 从 Apple 获取签名证书并通过 Merchant Administration 上传到网关。
如果您想要解密服务器上的付款令牌，请参阅解密付款令牌。
- 在付款确认中，请在 Authorize/Pay 或 Update Session 请求中提供以下字段。
order.walletProvider=APPLE_PAYorder.amount: 您提供的值必须是订单的最终金额（包括运费及其他金额）。order.currencysourceOfFunds.provided.card.devicePayment.paymentToken: 从 Apple Pay SDK 获取的加密付款令牌。 例如，PKPaymentToken.paymentData中的值
sourceOfFunds.provided.card.devicePayment.paymentToken [REST][NVP]
- 网关将为您解密付款令牌，并使用解密的数据处理交易。
除标准字段外，使用付款令牌成功授权还会返回以下响应字段。
sourceOfFunds.provided.card.encryption=DEVICEsourceOfFunds.provided.card.deviceSpecificNumber: 隐藏格式的 DPAN。sourceOfFunds.provided.card.deviceSpecificExpiry.monthsourceOfFunds.provided.card.deviceSpecificExpiry.yearsourceOfFunds.provided.card.number: 隐藏格式的 FPAN。sourceOfFunds.provided.card.expiry.month: 卡过期月份。sourceOfFunds.provided.card.expiry.year: 卡过期年份。sourceOfFunds.provided.card.devicePayment.cryptogramFormat
请求示例
下面是付款令牌由网关解密的 REST 中的 Authorization 请求示例。
{
"apiOperation": "AUTHORIZE",
"order": {
"currency": "USD",
"amount": "61.00",
"walletProvider": "APPLE_PAY"
},
"sourceOfFunds": {
"type": "CARD",
"provided":{
"card":{
"devicePayment":{
"paymentToken":"{\r\n\t\"version\": \"EC_v1\",\r\n\t\"data\":\"WO\/fTbdARsB1Rg3tS4ISwNG4cWDRk3JZDSbP32iDdeMP7UFouS...\",
\r\n\t\"signature\": \"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkg...\",
\r\n\t\"header\": {\r\n\t\t\"transactionId\": \"c162557e7ae1c69a47583bc2364d1a3e531428d13fb664032f9e09fa37381fc1\",
\r\n\t\t\"ephemeralPublicKey\": \"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMeuRqVEOZAQ...\",
\r\n\t\t\"publicKeyHash\": \"tBGp1mEoHLiHwfOkazpKVbf3cMKmVS98PGufUJ2Q3ys=\"\r\n\t}\r\n}"
//This is only a sample token and will not pass validation. You should substitute this with an actual payment token returned from Apple Pay (PKPaymentToken.paymentData).
//The gateway considers this value to be a string, NOT JSON itself. The parenthesis are a part of the string.
}
}
}
},
"transaction": {
"source": "INTERNET"
}
}
响应示例
{
"authorizationResponse": {
"commercialCard": "123",
"commercialCardIndicator": "1",
"date": "0314",
"financialNetworkCode": "MCC",
"posData": "1025104006600",
"posEntryMode": "812",
"processingCode": "003000",
"responseCode": "00",
"stan": "46465",
"time": "101534",
"transactionIdentifier": "447345902",
"transactionIntegrityClass": "A1"
},
"device": {
"ani": "12341234"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTMERCHANT",
"order": {
"amount": 30.10,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"certainty": "FINAL",
"chargeback": {
"amount": 0,
"currency": "USD"
},
"creationTime": "2023-03-14T10:15:33.819Z",
"currency": "USD",
"id": "844205983",
"lastUpdatedTime": "2023-03-14T10:15:34.265Z",
"merchantAmount": 30.10,
"merchantCategoryCode": "1234",
"merchantCurrency": "USD",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 30.10,
"totalCapturedAmount": 0.00,
"totalDisbursedAmount": 0.00,
"totalRefundedAmount": 0.00,
"walletProvider": "APPLE_PAY"
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Approved",
"gatewayCode": "APPROVED",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"devicePayment": {
"cryptogramFormat": "3DSECURE"
},
"deviceSpecificExpiry": {
"month": "1",
"year": "39"
},
"deviceSpecificNumber": "512345xxxxxx0008",
"fundingMethod": "UNKNOWN",
"number": "xxxxxxxxxxxxxxxx",
"scheme": "MASTERCARD",
"storedOnFile": "NOT_STORED"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2023-03-14T10:15:34.265Z",
"timeOfRecord": "2023-03-14T10:15:33.930Z",
"transaction": {
"acquirer": {
"batch": 20230314,
"date": "0314",
"id": "SYSTEST_ACQ_S2I",
"merchantId": "12345678",
"transactionId": "447345902"
},
"amount": 30.10,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"authorizationCode": "112233",
"currency": "USD",
"id": "950596203",
"receipt": "307310046465",
"source": "INTERNET",
"stan": "46465",
"terminal": "1111",
"type": "AUTHORIZATION"
},
"version": "71"
}
对付款令牌解密
您可以选择在服务器上解密付款令牌，而不是向网关提供要解密的付款令牌。 这种情况下，您需要负责存储加密凭据并执行解密。
DirectAPI 版本 40 之前的版本提供对 Apple Pay 付款令牌进行商家管理解密的支持。
- 付款确认后，将 Apple Pay 返回的加密付款令牌提交到您的服务器。
- 使用您的私人密钥在服务器上对付款令牌解密。 请参见此处的解密步骤。
- 在 Authorize/Pay 请求或 Update Session 请求中对应的交易字段内提供解密令牌的付款数据密钥。
Apple Pay JSON 密钥对应的 API 请求字段说明applicationPrimaryAccountNumber sourceOfFunds.provided.card.number 为此交易提供资金的卡的设备特定主要账号（即令牌或 DPAN）。 applicationExpirationDate sourceOfFunds.provided.card.expiry.month
sourceOfFunds.provided.card.expiry.yearapplicationPrimaryAccountNumber 的过期日期。 cardholderName sourceOfFunds.provided.card.nameOnCard （可选）持卡人姓名。 currencyCode order.currency 交易的 ISO 4217 货币代码。 transactionAmount order.amount 订单金额。 paymentDataType sourceOfFunds.provided.card.
devicePayment.cryptogramFormat密文格式。 将此项设置为 3DSECURE。 onlinePaymentCryptogram sourceOfFunds.provided.card.devicePayment.
onlinePaymentCryptogram3DSecure 格式的密文。 eciIndicator sourceOfFunds.provided.card.devicePayment.
eciIndicator提供电子商务指示器 (ECI)（如果有）。 - 除上述字段外，将这些字段包含在 Authorize/Pay 或 Update Session 请求中，并提交到网关。
- transaction.source=INTERNET
- order.walletProvider=APPLE_PAY
- device.mobilePhoneModel： （可选）用于发起付款的移动设备的识别码。
- posTerminal.location： 您可以指定
PAYER_TERMINAL_OFF_PREMISES或PAYER_TERMINAL_ON_PREMISES。 如果您未提供值，将使用PAYER_TERMINAL_OFF_PREMISES。
请求示例
这里是将解密付款令牌的值提供到网关的 REST 中的 Authorization 请求示例。
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "30.10",
"currency": "USD",
"walletProvider": "APPLE_PAY"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "512345000000X008", Replace "X" with "0"
"expiry": {
"month": "01",
"year": "39"
},
"devicePayment": {
"cryptogramFormat": "3DSECURE",
"onlinePaymentCryptogram": "IA/8pdiWftSsxpFT6wABoDABhgA=",
"eciIndicator": "20"
}
}
},
"type": "CARD"
},
"device": {
"ani": "12341234"
},
"transaction": {
"source": "INTERNET"
}
}
响应示例
{
"authorizationResponse": {
"commercialCard": "123",
"commercialCardIndicator": "1",
"date": "0329",
"financialNetworkCode": "MCC",
"posData": "1025104006600",
"posEntryMode": "812",
"processingCode": "003000",
"responseCode": "00",
"stan": "287916",
"time": "005723",
"transactionIdentifier": "260113124",
"transactionIntegrityClass": "A1"
},
"device": {
"ani": "12341234"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TEST_MERCHANT",
"order": {
"amount": 30.1,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"certainty": "ESTIMATED",
"chargeback": {
"amount": 0,
"currency": "USD"
},
"creationTime": "2022-03-29T00:57:22.553Z",
"currency": "USD",
"id": "C999903",
"lastUpdatedTime": "2022-03-29T00:57:23.813Z",
"merchantAmount": 30.1,
"merchantCategoryCode": "1234",
"merchantCurrency": "USD",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 30.1,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0,
"walletProvider": "APPLE_PAY"
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Approved",
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"devicePayment": {
"cryptogramFormat": "3DSECURE"
},
"deviceSpecificExpiry": {
"month": "1",
"year": "39"
},
"deviceSpecificNumber": "512345xxxxxx0008",
"fundingMethod": "UNKNOWN",
"number": "xxxxxxxxxxxxxxxx",
"scheme": "MASTERCARD",
"storedOnFile": "NOT_STORED"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-03-29T00:57:23.813Z",
"timeOfRecord": "2022-03-29T00:57:22.675Z",
"transaction": {
"acquirer": {
"batch": 20220329,
"date": "0329",
"id": "TESTACQUIRER",
"merchantId": "123463",
"transactionId": "260113124"
},
"amount": 30.1,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"authorizationCode": "112233",
"currency": "USD",
"id": "1",
"receipt": "208800287916",
"source": "INTERNET",
"stan": "287916",
"terminal": "12333",
"type": "AUTHORIZATION"
},
"version": "71"
}
测试 Apple Pay 集成
您可以使用测试商家配置文件和支持的由 Apple 提供的用于沙盒测试的 FPAN 测试与网关的集成。
您必须使用您的网关测试商家配置文件将应用配置为使用 Apple Pay 沙盒环境。 当付款人在 Apple Pay 中选择卡时，应用将在测试模式下生成付款令牌。
如果您在解密付款令牌，请使用已解密令牌中的 DPAN 执行测试交易。
如果网关解密付款令牌，您必须从 Apple 获取签名证书，并在生产环境中使用您的网关测试商家配置文件通过 Merchant Administration 将其上传到网关。 网关将使用此证书解密付款令牌。
由于 Apple Pay 卡总是在变化，Mastercard Gateway 无法与一个商家的更改同步，也无法保留系统来处理批准的交易。 因此，它会一直拒绝。
通过 Apple Pay Mobile SDK
Mobile SDK 帮助您开发将通过 Mastercard Gateway 接受数字付款的移动应用程序（应用）。 网关通过 Mobile SDK 提供 Apple Pay 支持。 单击此处获取 iOS 平台的 Mobile SDK 集成指南。