- 集成指南
- 支持的功能（付款方式）
- 实施浏览器付款集成
- PayPal
- 通过网关集成到 PayPal JS SDK
通过网关集成到 PayPal JS SDK
本指南介绍如何通过集成到网关提供的 PayPal JavaScript SDK 将 PayPal Smart Button 添加到您的付款页。
先决条件
使用网关的 PayPal JavaScript SDK 向您的付款人提供 PayPal Smart Button 作为结账选项：
- 确保 your payment service provider 已在您的商家配置文件中启用 PayPal。
- 从 Merchant Administration 中的管理菜单，单击 PayPal 配置，按照说明注册 PayPal 并为商家配置文件启用 PayPal。 您必须有所需权限才能更新 PayPal 配置。
使用网关的 PayPal JavaScript SDK 添加智能按钮
请按照下方列出的步骤构建与网关的 PayPal JavaScript SDK 的集成。
步骤 1： 创建会话
网关的 PayPal JavaScript SDK 使用基于会话的身份验证。 创建会话来更新您要存储的请求字段和值。
要创建会话，请从服务器端应用程序提交 Create Session 请求。 响应将返回一个会话 ID，您必须在后续步骤中使用此 ID 来引用此会话。
请求示例
| URL | https://qnbalahli.test.gateway.mastercard.com/api /rest/version/72/merchant/<your_gateway_merchant_ID>/session |
| HTTP 方法 | POST |
步骤 2： 使用订单、交易和浏览器付款详细信息更新会话
通过从您的服务器端应用程序提交 Update Session 请求来更新会话中的订单金额和货币。
通过从您的服务器端应用程序提交 Update Session 请求来更新会话，至少更新订单 ID、交易 ID、订单金额、货币和浏览器付款详细信息（付款确认）。
提供
browserPayment.returnUrl 是可选的，因为呈现 PayPal Smart Button 交互使其工作不需要它。请求示例
| URL | https://qnbalahli.test.gateway.mastercard.com/api /rest/version/72/merchant/<your_gateway_merchant_ID>/session>/<your_session_ID> |
| HTTP 方法 | PUT |
{
"apiOperation": "UPDATE_SESSION",
"browserPayment": {
"operation": "PAY",
"paypal": {
"paymentConfirmation": "CONFIRM_AT_PROVIDER"
}
},
"order": {
"amount": "679.99",
"currency": "USD"
},
"sourceOfFunds": {
"type": "PAYPAL"
}
}
步骤 3： 在您的付款页中包含网关 PayPal JS SDK
通过在 head 元素内添加 script 元素，在付款页包含网关的 PayPal JavaScript SDK (gateway-paypal.js)。 这会将 GatewayPaypal 对象放入窗口名称空间。
<script type="text/javascript" src="https://qnbalahli.test.gateway.mastercard.com/static/gateway-paypal/1.2.0/gateway-paypal.min.js"></script>
步骤 4： 配置网关 PayPal 交互
加载您的付款页时，通过调用 GatewayPaypal.configure（config、errorCallback、completeCallback、cancelCallback）发起 PayPal 交互。 这会将您的付款页重定向到网关 PayPal 方法的 configure.html。
请求示例
function errorCallback(error) {
};
function completeCallback(response) {
};
function cancelCallback(response) {
};
var config = {
merchantId: '<your_gateway_merchant_ID>', // required
orderId: '<order_ID>',//required and must match the value provided in Step 2
transactionId: '<transaction id>',// required and must match the value provided in Step 2
sessionId: '<your_session_ID>',// required
currency: '<order_currency>', // required
paymentConfirmation: '<confirmation_of_payment>', // optional, must be one of CONFIRM_AT_PROVIDER (if you want the payer to commit to the payment on the PayPal website) or CONFIRM_AT_MERCHANT (if you want the payer to commit to the payment on your website). If not provided, the value is defaulted to "CONFIRM_AT_PROVIDER".
operation: '<type_of_transaction>', // required, must be one of AUTHORIZE (transaction created in the gateway is an AUTHORIZATION transaction) or PAY (transaction created in the gateway is a PAYMENT transaction). For a successful Authorization transaction, submit a CAPTURE request to move the funds from the payer's account to your account.
apiVersion: '',// optional, Must be version 60 or above. If not provided, the value is defaulted to 60.
buttonElement: '',// required
style: {// Style options for customizing the PayPal Smart Button.
color: '<color_of_the_button>', // optional, must be one of "gold" (Recommended by PayPal), "blue", "silver", "white", "black"
shape: '<shape_of_the_button>', // optional, must be one of "rect", "pill". If not provided, the value is defaulted to "rect".
label: '<label_on_the_button>', // optional, must be one of "paypal", "checkout", "buynow", "pay". If not provided, the value is defaulted to "paypal".
tagline: '<tagline_to_be_displayed>', // optional, must be one of "true", "false". If not provided, the value is defaulted to "true".
size: '<size_of_the_button>' // optional. If not provided, the value is defaulted to the size of its container element. To customize the button width, alter the width of the container element. To customize the button height, set the height option to a value from 25 to 55.
}
};
GatewayPaypal.configure(config, errorCallback, completeCallback, cancelCallback);
merchantId
merchantId 是必需的，让网关可以正确确定您的付款选项。
apiVersion
SDK apiVersion 必须与您提交 Create Session 请求时使用的版本匹配。 例如，在创建会话时，如果您使用 apiVersion 61，则应确保对与其相关的所有其他配置使用相同的 apiVersion。 如果两个 apiVersion 不匹配，操作将失败。
默认情况下，config() 上的
apiVersion 是 61。如果您不为 apiVersion 提供值，系统将考虑使用默认值。buttonElement
确定按钮在页面上的位置。 它是按钮呈现的 DOM 元素的标识符。
paymentConfirmation
指示您希望付款人在结账流中的哪个位置进行付款，可以在您的网站上或在 PayPal 上。
错误响应
GatewayPaypal.configure() 调用可能返回以下错误响应。
| response.cause | resp.explanation | 所需操作 |
|---|---|---|
| 错误 | 缺少参数： Merchant ID、Hosted Session ID、Payment Confirmation、Button Element 和三个回调函数是 configure() 方法需要的全部参数。 | 修复您的集成。 提供所有强制请求字段。 |
| 错误 |
|
提供正确的函数修复您的集成。 |
| 错误 | API 版本必须为 <MIN_VERSION> 或更高版本。 | 修复您的集成。 将 apiVersion 设置为 60 或更高版本。 |
付款确认
不论是使用使用 PayPal 结账还是使用 PayPal 付款结账流，您都可以选择在 PayPal 上显示立即付款按钮或继续按钮。
在 PayPal 上确认付款
通过提交 CONFIRM_AT_PROVIDER，立即付款按钮将在 PayPal 的模式中显示。 使用立即付款按钮，付款人可以在 PayPal 模式中确认付款。 此选择让您可以为付款人提供更快速的结账体验，因为付款人在 PayPal 上完成付款。
如果付款人在 PayPal 网站上进行付款，您可以向网关提交 Retrieve Transaction 或 Retrieve Order 请求来验证交易结果。 然后您可以显示带有最新详细信息的付款完成页面。
拒绝恢复
仅使用 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() 函数以允许付款人选择其他工具。
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": "CCREJECT-REFUSED@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"
}
在您的购物网站上确认付款
通过提交 CONFIRM_AT_MERCHANT，“继续”按钮将在 PayPal 的模式中显示。
使用继续按钮，付款人可以在完成与 PayPal 模式的交互后被重定向到您的购物网站来确认付款。 此选项允许您在接受付款前更改订单（如有必要）（例如，根据 PayPal 返回的地址添加送货和处理费用）。
如果付款人在您的网站上进行付款，即使用 CONFIRM_AT_MERCHANT 作为付款确认，付款确认页面将显示给付款人。 您可以向网关提交 Retrieve Transaction 或 Retrieve Order 请求来验证交易结果。 付款人决定继续付款后，您必须向网关提交 CONFIRM_BROWSER_PAYMENT 来完成付款。 然后您可以显示带有最新详细信息的付款完成页面。 您可以使用此操作更新付款的属性（如运费）来反映付款人在 PayPal UI 上选择的送货详细信息。
CONFIRM_AT_MERCHANT（使用 PayPal 结账）不支持拒绝恢复。
请求示例
{
"apiOperation": "CONFIRM_BROWSER_PAYMENT",
"order": {
"amount": "779.99",
"currency": "USD",
"shippingAndHandlingAmount": "100.00"
}
}
检索交易详细信息
您可以通过以下选项来检索 PayPal 交互的交易详细信息：
- Retrieve Order 或 Retrieve Transaction 操作
- Merchant Administration 中的订单和交易搜索： 使用付款收据上提供给付款人的参考号查看交易详细信息。 参考号将在付款人和您的银行账单上提供。 让您可以进一步验证交易。
了解订单和交易状态
browserPayment.paypal.paymentConfirmation 为 CONFIRM_AT_PROVIDER
| 浏览器付款交互状态 | 交易网关响应代码 | 订单状态 | 说明 |
|---|---|---|---|
| browserPayment.interaction.status=INITIATED | response.gatewayCode=SUBMITTED | order.status=INITIATED | 您已使用 INITIATE_BROWSER_PAYMENT 操作提交了交易。 |
| browserPayment.interaction.status=COMPLETED | response.gatewayCode=APPROVED | order.status=CAPTURED | 付款人已点击立即付款按钮，CONFIRM_BROWSER_PAYMENT 请求已提交。 |
如果是拒绝恢复，当您收到
INSTRUMENT_DECLINED 时，response.gatewayCode 的状态将是 SUBMITTED，order.status 的状态将是 INITIATED。 如果在前两次尝试付款时工具被拒绝，此状态将保持不变。 如果在第三次尝试时工具也被拒绝，交易将被拒绝，响应 .gatewayCode 和 order.status 的状态将分别变为 DECLINED 和 FAILED。browserPayment.paypal.paymentConfirmation 为 CONFIRM_AT_MERCHANT
| 浏览器付款交互状态 | 交易网关响应代码 | 订单状态 | 说明 |
|---|---|---|---|
| browserPayment.interaction.status=INITIATED | response.gatewayCode=SUBMITTED | order.status=INITIATED | 您已使用 INITIATE_BROWSER_PAYMENT 操作提交了交易。 |
| browserPayment.interaction.status=RETURNED_TO_MERCHANT | response.gatewayCode=SUBMITTED | order.status=INITIATED | 付款人已在 PayPal 中点击了继续按钮，UPDATE_BROWSER_PAYMENT 操作已提交 |
| browserPayment.interaction.status=COMPLETED | response.gatewayCode=APPROVED | order.status=CAPTURED | 您已提交 CONFIRM_BROWSER_PAYMENT 操作。 |
测试您的集成
通过网关完成与 PayPal 的集成后，您可以使用 PayPal 沙盒进行测试。
要开始测试，请创建一个 PayPal 账户，然后在通过 your payment service provider 设置您的商家配置文件时使用这些凭据。 请确保使用非测试商家进行这些交易。
- 请使用您在 PayPal 沙盒中创建的商家配置文件。
- 请使用上述步骤进行集成。
- 请确保您已在 Merchant Administration 中配置了 PayPal 集成，并已向网关授予代表您进行交易的第三方权限。