- 集成指南
- 支持的功能（付款方式）
- 实施浏览器付款集成
- PayPal
- 直接集成到 PayPal JS SDK
直接集成到 PayPal JS SDK
本指南介绍如何通过直接集成到 PayPal 的 JavaScript SDK 将 PayPal Smart Button 添加到您的付款页。
先决条件
使用 PayPal 的 JavaScript SDK 向您的付款人提供 PayPal Smart Button 作为结账选项：
- 确保 your payment service provider 有 PayPal 账户，并且已使用其 PayPal 账户创建了应用程序。Your payment service provider 应该已从 PayPal 收到客户端 ID，并根据您在商家管理器中的商家配置文件存储该 ID。
- 请确保您已在 Merchant Administration 中配置了 PayPal 集成，并已向网关授予代表您进行交易的第三方权限。
信息流
以下步骤介绍直接集成到 PayPal JS SDK 的信息流：
- 付款人在您的付款页上点击 PayPal Smart Button。
- 付款人浏览器中的 Javascript 向您的服务器发送请求。
- 您的服务器在网关上执行 Initiate Browser Payment 操作以开始使用 PayPal 的付款流程。
- 网关将来自 PayPal 的交互 ID 返回到您的服务器。
- 您的服务器将交互 ID 返回到在付款人浏览器中运行的 Javascript。
- 付款人的浏览器随后显示 PayPal UI。
- 付款人浏览器中的 Javascript 与您的服务器交互以继续执行付款流程。
- 您的服务器在网关上执行 Confirm Browser Payment 操作以完成付款。
使用 PayPal 的 JavaScript SDK 添加智能按钮
请按照下方列出的步骤构建与 PayPal 的 JavaScript SDK 的集成。
步骤 1： 获取客户端 ID
通过向网关提交 Payment Options Inquiry 请求获取客户端 ID。 响应将返回一个客户端 ID，您必须在后续步骤中使用此 ID。
请求示例
https://<your_host_name>/api/rest/version/<api_version>/merchant/<your_gateway_merchantId>/paymentOptionsInquiry
响应示例
{
"merchant": "TESTPP_V2_MER33;",
"paymentTypes": {
"paypal": {
"currencies": [
{
"currency": "AUD"
},
],
"transactionSources": [
{
"transactionSource": "INTERNET"
}
]
"clientId": "ARLDC7ynAfGNlnJy8PuLanMRQvteg9RsfxAMLK-43amD5_urCn0Jl1APryAyWEvIm_GY1ippISEwsoza",
"accountId": "RMU2YU3VN8SUL"
}
},
"result": "SUCCESS",
"supportedPaymentOperations": [
{
"supportedPaymentOperation": "AUTHORIZE"
}
]
}
步骤 2： 将 PayPal JavaScript SDK 添加到您的网页
要启用 PayPal Smart Button 功能，请将 PayPal JavaScript SDK 添加到您的网页中。 使用您在步骤 1 中的 Payment Options Inquiry 的响应中收到的客户端 ID 作为 client-id 查询参数的值。
示例 HTML 代码
<!DOCTYPE html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
</head>
<body>
<script src="https://www.paypal.com/sdk/js?client-id=PayPal_CLIENT_ID and merchant-id=PayPal_MERCHANT_ID">
</script>
</body>
有关此步骤的更多详细信息，请参见 PayPal 开发人员指南中的步骤 2。
步骤 3： 在您的网页上呈现 PayPal 智能按钮
要在您的网页上呈现 PayPal Smart Button，请将以下代码添加到您的网页中。 使用您在步骤 1 中的 Payment Options Inquiry 的响应中收到的客户端 ID。
示例
<body>
<script src="https://www.paypal.com/sdk/js?client-id=PayPal_CLIENT_ID and merchant-id=PayPal_MERCHANT_ID">
</script>
<div id="paypal-button-container"></div>
<script>
paypal.Buttons().render('#paypal-button-container'); // This function displays Smart Payment Buttons on your web page.
</script>
</body>
有关此步骤的更多详细信息，请参见 PayPal 开发人员指南中的步骤 3。
步骤 4： 建立交易
您必须设置 createOrder 回调来通知您的主机向网关提交 Initiate Browser Payment 请求。 要从您的服务器或客户端设置交易，请参见“PayPal 开发人员”指南中的设置交易部分。
事件序列因 PayPal 结账流而异。
- 对于“使用 PayPal 结账”，请参见使用 PayPal 结账期间的事件序列部分。
- 对于“使用 PayPal 付款”，请参见使用 PayPal 付款期间的事件序列部分。
使用 PayPal 结账期间的事件序列
- 使用
browserPayment.paypal.paymentconfirmation = CONFIRM_AT_MERCHANT向网关提交 Initiate Browser Payment 请求请求示例{ "apiOperation": "INITIATE_BROWSER_PAYMENT", "browserPayment": { "operation": "PAY", "paypal": { "paymentConfirmation": "CONFIRM_AT_MERCHANT" } }, "order": { "amount": "679.99", "currency": "USD" }, "sourceOfFunds": { "type": "PAYPAL" } }响应示例"browserPayment.paypal.interactionId": "EC-8AT72418NV353182U" - 实现一个回调处理程序，当付款人点击 PayPal Smart Button（在步骤 4 的示例中显示为
createOrderCallbackHandler）时调用该处理程序。 此处理程序必须与您的服务器交互以向网关提交 Initiate Browser Payment 请求。 - 从您的服务器提交 Initiate Browser Payment 请求，然后返回
browserPayment.paypal.interactionId。Initiate Browser Payment 响应在
browserPayment.paypal.interactionId字段中包含快速结账令牌。请求示例createOrder: function() { return fetch('/my-server/create-paypal-transaction', { method: 'post', headers: { 'content-type': 'application/json' } }).then(function(res) { return res.json(); }).then(function(data) { return data.interactionId; // Return the interactionId as provided by the gateway to your server }); } - PayPal JavaScript 从 PayPal 获取付款单，然后在付款人的浏览器上呈现此表单。
- 付款人登录到 PayPal，并将付款详细信息提交到 PayPal。
- 向 PayPal 注册 onApprove 处理程序。
- PayPal UI 上的交易成功后，onApprove 处理程序将被调用。 现在，从您的服务器向网关提交 Update Browser Payment 请求以获取最新的付款详细信息。
approveCallback 处理程序
onApprove: function (data, actions) { // CALL TO UPDATE_BROWSER_PAYMENT from your server; };Update Browser Payment 请求示例//URL https://<your_host_name>/api/rest/version/latest/merchant/<your_merchant_id>/transaction/151109242cvbnv //Body { "apiOperation": "UPDATE_BROWSER_PAYMENT" }Update Browser Payment 响应示例{ "device": { "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36", "ipAddress": "66.159.204.102" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "TESTMAN1234", "order": { "amount": 679.99, "chargeback": { "amount": 0, "currency": "USD" }, "creationTime": "2020-09-17T09:38:41.924Z", "currency": "USD", "id": "421d49456789012345678909234527890", "lastUpdatedTime": "2020-09-17T09:40:11.894Z", "merchantAmount": 679.99, "merchantCurrency": "USD", "status": "CAPTURED", "totalAuthorizedAmount": 679.99, "totalCapturedAmount": 679.99, "totalRefundedAmount": 0 }, "response": { "acquirerCode": "Success", "gatewayCode": "APPROVED" }, "result": "SUCCESS", "shipping": { "address": { "city": "Market City", "country": "AUS", "postcodeZip": "4322", "stateProvince": "Queensland", "street": "35 Rainbow street", "street2": "Floor 5, Apartment 34" }, "contact": { "firstName": "John", "lastName": "Smith", "phone": "0745231111" } }, "timeOfLastUpdate": "2020-09-17T09:40:11.894Z", "timeOfRecord": "2020-09-17T09:38:41.945Z", "transaction": { "acquirer": { "date": "2020-09-17", "id": "PAYPAL", "merchantId": "m.m@g.com", "time": "09:40:11", "transactionId": "SVE2APDYOXKMA7RY0" }, "amount": 679.99, "currency": "USD", "id": "151109242cvbnv", "receipt": "SVE2APDYOXKMA7RY0", "source": "INTERNET", "stan": "0", "type": "PAYMENT", "update": [ { "gatewayCode": "SUBMITTED", "time": "2020-09-17T09:38:42.054Z" }, { "gatewayCode": "APPROVED", "time": "2020-09-17T09:40:11.896Z" } ] }, "version": "59" } - 如果由于运费金额的变化导致金额发生任何变化，您将向付款人显示增量金额。
- 付款人确认付款后，提交 CONFIRM_BROWSER_PAYMENT 请求以完成交易。
请求示例
{ "apiOperation": "CONFIRM_BROWSER_PAYMENT", "order": { "amount": "779.99", // amount updated as a result of updated shipping and handling charges "shippingAndHandlingAmount": "100.00" // updated shipping and handling charges ... } }
CONFIRM_AT_MERCHANT（即使用 PayPal 结账）不支持拒绝恢复。
使用 PayPal 付款期间的事件序列
- 向网关提交 Initiate Browser Payment 请求，其中的
browserPayment.paypal.paymentconfirmation = CONFIRM_AT_PROVIDER请求示例{ "apiOperation": "INITIATE_BROWSER_PAYMENT", "browserPayment": { "operation": "PAY", "paypal": { "paymentConfirmation": "CONFIRM_AT_PROVIDER" } }, "order": { "amount": "679.99", "currency": "USD" }, "sourceOfFunds": { "type": "PAYPAL" } }响应示例"browserPayment.paypal.interactionId": "EC-8AT72418NV353182U" - 在 PayPal Smart Button 代码中实现
createOrder回调。 当付款人点击 PayPal Smart Button 时，PayPal 将执行此代码。 - 从您的服务器提交 Initiate Browser Payment 请求，然后返回
browserPayment.paypal.interactionId。Initiate Browser Payment 响应包含字段
browserPayment.paypal.interactionId。示例createOrder: function() { return fetch('/my-server/create-paypal-transaction', { method: 'post', headers: { 'content-type': 'application/json' } }).then(function(res) { return res.json(); }).then(function(data) { return data.interactionId; // Return the interactionId as provided by the gateway to your server }); } - PayPal JavaScript 从 PayPal 获取付款单，然后在付款人的浏览器上呈现此表单。
- 付款人登录到 PayPal，并将付款详细信息提交到 PayPal。
- 向 PayPal 注册 onApproveCallback 处理程序。
- PayPal UI 上的交易成功后，
onApprove处理程序将被调用。 现在，从您的服务器向网关提交 CONFIRM_BROWSER_PAYMENT 请求以完成付款。approveCallback 处理程序onApprove: function (data, actions) { // CALL TO CONFIRM_BROWSER_PAYMENT from your server; };请求示例{ "apiOperation": "CONFIRM_BROWSER_PAYMENT" } - （可选）如果工具被拒绝，PayPal 向 Execute Payment 请求发送
INSTRUMENT_DECLINED响应。付款人一共可以尝试 3 次付款。 有关详细信息，请参阅拒绝恢复。
您必须执行
action.restart()才能够支持 DECLINE_RECOVERY。
拒绝恢复
仅使用 PayPal 时支持拒绝恢复。 在交易过程中，如果工具被拒绝，付款人还可以再进行两次付款尝试。 在全部三次尝试中，付款人可以使用在 PayPal 注册的相同工具或任何其他工具继续付款。 如果是新工具，付款人必须在继续付款之前向 PayPal 注册。 付款人一共可以尝试 3 次付款。 如果在第三次尝试后工具仍被拒绝，your payment service provider 将发送 TRANSACTION_REFUSED 或 INSTRUMENT_DECLINED 响应。 此后，付款人将无法继续完成交易过程。
拒绝恢复过程中的事件序列
- 向网关提交 Initiate Browser Payment 请求，其中的 browserPayment.paypal.paymentconfirmation = CONFIRM_AT_PROVIDER。
PayPal 的付款单将显示。
- 付款人登录到 PayPal 的付款单，选择支付工具，然后单击立即付款。
- 提交 CONFIRM_BROWSER_PAYMENT 请求调用 PayPal 的 Execute Payment 请求。
- 如果工具被拒绝，PayPal 会向 Execute Payment 请求发送
INSTRUMENT_DECLINED响应。付款人一共可以尝试 3 次付款。
- 在 onApprove 事件处理程序收到 INSTRUMENT_DECLINED 响应后，调用 actions.restart() 函数以允许付款人选择其他工具。
CONFIRM_AT_MERCHANT（使用 PayPal 结账）不支持拒绝恢复。
action.restart()
const restartPaymentOnInstrumentDeclined = (resp, actions) => {
if (isInstrumentDeclined(resp)) {
return actions.restart();
} else {
gatewaySuccessCallbackBP(resp);
}
}
INSTRUMENT_DECLINED
{
"browserPayment": {
"interaction": {
"status": "INITIATED",
"timeInitiated": "2021-07-15T07:10:16.176Z"
},
"operation": "PAY",
"paypal": {
"displayShippingAddress": true,
"interactionId": "EC-9SH774983H4356451",
"overrideShippingAddress": true,
"paymentConfirmation": "CONFIRM_AT_PROVIDER"
}
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "PP_POI_1",
"order": {
"amount": 931,
"chargeback": {
"amount": 0,
"currency": "USD"
},
"creationTime": "2021-07-15T07:10:16.152Z",
"currency": "USD",
"id": "vcc-206",
"item": [
{
"brand": "MC",
"category": "NA",
"detail": {
"unitDiscountRate": 0
},
"name": "name",
"quantity": 1,
"sku": "sku",
"unitDiscountAmount": 0,
"unitPrice": 931
}
],
"itemAmount": 931,
"lastUpdatedTime": "2021-07-15T07:12:19.571Z",
"merchantAmount": 931,
"merchantCurrency": "USD",
"reference": "my order",
"status": "INITIATED",
"taxAmount": 0,
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"acquirerCode": "INSTRUMENT_DECLINED",
"acquirerMessage": "",
"debugInformation": "INSTRUMENT_DECLINED, The instrument presented was either declined by the processor or bank, or it can't be used for this payment., e5a837ee6834",
"gatewayCode": "SUBMITTED"
},
"result": "SUCCESS",
"shipping": {
"address": {
"city": "Los Angeles",
"company": "Google",
"country": "USA",
"postcodeZip": "90001",
"stateProvince": "CA",
"street": "2nd Main",
"street2": "lane 2"
},
"contact": {
"email": "ramakanth@gmail.com",
"firstName": "Ramakanth",
"lastName": "Kulkarni",
"mobilePhone": "9999999999",
"phone": "9999999999"
}
},
"sourceOfFunds": {
"provided": {
"paypal": {
"accountEmail": "johnsmith@paypal.com",
"accountHolder": "Paul Levetsky",
"payerId": "LM9AM5Y34N3X8"
}
},
"type": "PAYPAL"
},
"timeOfLastUpdate": "2021-07-15T07:12:19.571Z",
"timeOfRecord": "2021-07-15T07:10:16.171Z",
"transaction": {
"acquirer": {
"date": "15 Jul 2021",
"id": "PAYPAL",
"merchantId": "NDXE9MFKNPCUA",
"time": "07:12:19"
},
"amount": 931,
"currency": "USD",
"id": "1",
"source": "INTERNET",
"stan": "0",
"type": "PAYMENT",
"update": [
{
"gatewayCode": "SUBMITTED",
"time": "2021-07-15T07:10:17.280Z"
}
]
},
"version": "62"
}
TRANSACTION_REFUSED
{
"browserPayment": {
"interaction": {
"status": "COMPLETED",
"timeCompleted": "2021-07-20T09:17:27.128Z",
"timeInitiated": "2021-07-20T09:15:56.313Z"
},
"operation": "PAY",
"paypal": {
"displayShippingAddress": true,
"interactionId": "EC-74C02380KE247305K",
"overrideShippingAddress": true,
"paymentConfirmation": "CONFIRM_AT_PROVIDER"
}
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "PP_POI_1",
"order": {
"amount": 1.28,
"chargeback": {
"amount": 0,
"currency": "USD"
},
"creationTime": "2021-07-20T09:15:56.278Z",
"currency": "USD",
"description": "Ordered goods",
"id": "testsdkhco33",
"item": [
{
"brand": "MC",
"category": "NA",
"name": "name",
"quantity": 1,
"sku": "sku",
"unitPrice": 1.28
}
],
"itemAmount": 1.28,
"lastUpdatedTime": "2021-07-20T09:17:27.136Z",
"merchantAmount": 1.28,
"merchantCurrency": "USD",
"reference": "my order",
"status": "FAILED",
"taxAmount": 0,
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"acquirerCode": "TRANSACTION_REFUSED",
"acquirerMessage": "",
"debugInformation": "TRANSACTION_REFUSED, The request was refused, cae635b964420",
"gatewayCode": "DECLINED"
},
"result": "FAILURE",
"shipping": {
"address": {
"city": "Los Angeles",
"country": "USA",
"postcodeZip": "90001",
"stateProvince": "CA",
"street": "2nd Main",
"street2": "lane 2"
},
"contact": {
"firstName": "Ramakanth",
"lastName": "Kulkarni"
}
},
"sourceOfFunds": {
"provided": {
"paypal": {
"accountEmail": "CCREJECT-REFUSED@paypal.com",
"accountHolder": "Paul Levetsky",
"payerId": "LM9AM5Y34N3X8"
}
},
"type": "PAYPAL"
},
"timeOfLastUpdate": "2021-07-20T09:17:27.136Z",
"timeOfRecord": "2021-07-20T09:15:56.308Z",
"transaction": {
"acquirer": {
"date": "20 Jul 2021",
"id": "PAYPAL",
"merchantId": "NDXE9MFKNPCUA",
"time": "09:17:27"
},
"amount": 1.28,
"currency": "USD",
"id": "1",
"source": "INTERNET",
"stan": "0",
"type": "PAYMENT",
"update": [
{
"gatewayCode": "SUBMITTED",
"time": "2021-07-20T09:15:57.482Z"
},
{
"gatewayCode": "DECLINED",
"time": "2021-07-20T09:17:27.128Z"
}
]
},
"version": "62"
}
测试您的集成
完成与 PayPal 的集成后，您可以使用 PayPal 沙盒进行测试。
要开始测试，请创建一个 PayPal 账户，然后在通过 your payment service provider 设置您的商家配置文件时使用这些凭据。 请确保使用非测试商家进行这些交易。
- 对集成使用上述步骤。
- 确保您提交 Payment Options Inquiry 请求来在响应中接收 your payment service provider 的客户端 ID。
- 请确保您已在 Merchant Administration 中配置了 PayPal 集成，并已向网关授予代表您进行交易的第三方权限。