- Pautas de integración
- Características soportadas (métodos de pago)
- Implementación de una integración de pago mediante explorador
- PayPal
- Integración directa al SDK de JS de PayPal
Integración directa al SDK de JS de PayPal
Esta guía describe cómo agregar el botón inteligente de PayPal a la página de pago mediante la integración directa con el SDK de JavaScript de PayPal.
Prerrequisitos
Para ofrecer el botón inteligente de PayPal como opción de pago a sus pagadores mediante el SDK de JavaScript de PayPal:
- Asegúrese de que your payment service provider tenga una cuenta con PayPal y haya creado una aplicación con su cuenta PayPal. Your payment service provider debe haber recibido el ID del cliente de PayPal y haberlo guardado con su perfil de negocio en Administrador de negocios.
- Asegúrese de haber configurado la integración de PayPal en Merchant Administration y haber otorgado permiso al tercero para que el motor de pagos realice transacciones en su nombre.
Flujo de información
Los siguientes pasos describen el flujo de información para una integración directa con el SDK de JS de PayPal:
- El pagador hace clic en el botón inteligente de PayPal en su página de pago.
- Javascript en el explorador del pagador envía una solicitud a su servidor.
- Su servidor realiza la operación Initiate Browser Payment en el motor de pagos para iniciar el proceso de pago con PayPal.
- El motor de pagos devuelve el ID de interacción de PayPal a su servidor.
- El servidor devuelve el ID de interacción al Javascript que se ejecuta en el explorador del pagador.
- El explorador del pagador muestra la interfaz de usuario de PayPal.
- El Javascript del explorador del pagador interactúa con su servidor para continuar con el proceso de pago.
- Su servidor realiza la operación Confirm Browser Payment en el motor de pagos para completar el pago.
Agregar un botón inteligente mediante el SDK de JavaScript de PayPal
Siga los pasos que se describen a continuación para crear su integración con el SDK de JavaScript de PayPal.
Paso 1: Obtener el ID del cliente
Obtenga el ID del cliente enviando la solicitud Payment Options Inquiry al motor de pagos. La respuesta devuelve un ID de cliente que se debe utilizar en los pasos posteriores.
Solicitud de ejemplo
https://<your_host_name>/api/rest/version/<api_version>/merchant/<your_gateway_merchantId>/paymentOptionsInquiry
Respuesta de ejemplo
{
"merchant": "TESTPP_V2_MER33;",
"paymentTypes": {
"paypal": {
"currencies": [
{
"currency": "AUD"
},
],
"transactionSources": [
{
"transactionSource": "INTERNET"
}
]
"clientId": "ARLDC7ynAfGNlnJy8PuLanMRQvteg9RsfxAMLK-43amD5_urCn0Jl1APryAyWEvIm_GY1ippISEwsoza",
"accountId": "RMU2YU3VN8SUL"
}
},
"result": "SUCCESS",
"supportedPaymentOperations": [
{
"supportedPaymentOperation": "AUTHORIZE"
}
]
}
Paso 2: Agregue el SDK de JavaScript de PayPal a su página web
Para habilitar la funcionalidad del botón inteligente de PayPal, agregue el SDK de JavaScript de PayPal a su página web. Utilice el ID de cliente que recibió en la respuesta de Payment Options Inquiry en el paso 1 como valor del parámetro de consulta de ID de cliente.
Código HTML de ejemplo
<!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>
Para obtener más detalles sobre este paso, consulte el paso 2 de la Guía para desarrolladores de PayPal.
Paso 3: Incluir el botón inteligente de PayPal en su página web
Para incluir el botón inteligente de PayPal en su página web, agregue el siguiente código a su página web. Utilice el ID de cliente que recibió en la respuesta de Payment Options Inquiry en el paso 1.
Ejemplo
<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>
Para obtener más detalles sobre este paso, consulte el paso 3 de la Guía para desarrolladores de PayPal.
Paso 4: Configurar una transacción
Debe configurar la devolución de llamada createOrder para informar a su host de que debe enviar la solicitud Initiate Browser Payment al motor de pagos. Para configurar una transacción desde su servidor o cliente, consulte la sección Configurar una transacción de la Guía para desarrolladores de PayPal.
La secuencia de sucesos difiere según el flujo de pago de PayPal.
- Para finalizar el pedido con PayPal, consulte la Secuencia de sucesos durante la finalización del pedido con PayPal.
- Para pagar con PayPal, consulte la Secuencia de sucesos durante el pago con PayPal.
Secuencia de eventos durante la finalización del pedido con PayPal
- Envíe la solicitud Initiate Browser Payment al motor de pagos con
browserPayment.paypal.paymentconfirmation = CONFIRM_AT_MERCHANTSolicitud de ejemplo{ "apiOperation": "INITIATE_BROWSER_PAYMENT", "browserPayment": { "operation": "PAY", "paypal": { "paymentConfirmation": "CONFIRM_AT_MERCHANT" } }, "order": { "amount": "679.99", "currency": "USD" }, "sourceOfFunds": { "type": "PAYPAL" } }Respuesta de ejemplo"browserPayment.paypal.interactionId": "EC-8AT72418NV353182U" - Implemente un controlador de devolución de llamada que se invoque cuando un pagador haga clic en el botón inteligente de PayPal (que se muestra como
createOrderCallbackHandleren el ejemplo del paso 4). Este controlador debe interactuar con su servidor para enviar la solicitud Initiate Browser Payment al motor de pagos. - Envíe la solicitud Initiate Browser Payment desde su servidor y devuelva
browserPayment.paypal.interactionId.La respuesta de Initiate Browser Payment contiene el token de pago rápido en el campo
browserPayment.paypal.interactionId.Solicitud de ejemplocreateOrder: 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 }); } - El JavaScript de PayPal obtiene el formulario de pago de PayPal y luego lo muestra en el explorador del pagador.
- El pagador inicia sesión en PayPal y envía los detalles del pago a PayPal.
- Registre el controlador onApprove con PayPal.
- Una vez que la transacción en la interfaz de usuario de PayPal se realiza correctamente, se invoca el controlador onApprove. Ahora, envíe la solicitud Update Browser Payment de su servidor al motor de pagos para obtener los últimos detalles de pago.
Controlador approveCallback
onApprove: function (data, actions) { // CALL TO UPDATE_BROWSER_PAYMENT from your server; };Ejemplo de solicitud Update Browser Payment//URL https://<your_host_name>/api/rest/version/latest/merchant/<your_merchant_id>/transaction/151109242cvbnv //Body { "apiOperation": "UPDATE_BROWSER_PAYMENT" }Ejemplo de respuesta de 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" } - Si hay algún cambio en el monto debido a un cambio en el monto del envío, debe mostrar el monto delta al pagador.
- Una vez que el pagador haya confirmado el pago, envíe la solicitud CONFIRM_BROWSER_PAYMENT para finalizar la transacción.
Solicitud de ejemplo
{ "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 ... } }
La recuperación ante rechazo no se admite con CONFIRM_AT_MERCHANT (es decir, finalizar el pago con PayPal).
Secuencia de eventos durante el pago con PayPal
- Envíe la solicitud Initiate Browser Payment al motor de pagos con
browserPayment.paypal.paymentconfirmation = CONFIRM_AT_PROVIDERSolicitud de ejemplo{ "apiOperation": "INITIATE_BROWSER_PAYMENT", "browserPayment": { "operation": "PAY", "paypal": { "paymentConfirmation": "CONFIRM_AT_PROVIDER" } }, "order": { "amount": "679.99", "currency": "USD" }, "sourceOfFunds": { "type": "PAYPAL" } }Respuesta de ejemplo"browserPayment.paypal.interactionId": "EC-8AT72418NV353182U" - Implemente la devolución de llamada
createOrderen el código del botón inteligente de PayPal. Cuando un pagador haga clic en el botón inteligente de PayPal, PayPal ejecutará este código. - Envíe la solicitud Initiate Browser Payment desde su servidor y devuelva
browserPayment.paypal.interactionId.La respuesta de Initiate Browser Payment contiene el campo
browserPayment.paypal.interactionId.EjemplocreateOrder: 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 }); } - El JavaScript de PayPal obtiene el formulario de pago de PayPal y luego lo muestra en el explorador del pagador.
- El pagador inicia sesión en PayPal y envía los detalles del pago a PayPal.
- Registre el controlador onApproveCallback con PayPal.
- Una vez que la transacción en la interfaz de usuario de PayPal se realiza correctamente, se invoca el controlador
onApprove. Ahora, envíe la solicitud CONFIRM_BROWSER_PAYMENT de su servidor al motor de pagos para finalizar el pago.Controlador approveCallbackonApprove: function (data, actions) { // CALL TO CONFIRM_BROWSER_PAYMENT from your server; };Solicitud de ejemplo{ "apiOperation": "CONFIRM_BROWSER_PAYMENT" } - (Opcional) Si se rechaza el instrumento, PayPal envía la respuesta
INSTRUMENT_DECLINEDa la solicitud Execute Payment.Un pagador tiene tres intentos en total para realizar el pago. Para obtener más información, consulte Recuperación ante rechazo.
Debe llevar a cabo
action.restart()para permitir DECLINE_RECOVERY.
Recuperación ante rechazo
La recuperación ante rechazo se admite solo con PayPal. Durante el proceso de transacción, si el instrumento se rechaza, el pagador tiene dos intentos más para realizar el pago. Para los tres intentos, un pagador puede usar el mismo o cualquier otro instrumento que esté registrado en PayPal para proceder con el pago. Si es un instrumento nuevo, el pagador debe registrarlo en PayPal antes de continuar con el pago. Un pagador tiene tres intentos en total para realizar el pago. Si incluso después del tercer intento se rechaza el instrumento, your payment service provider enviará la respuesta TRANSACTION_REFUSED o INSTRUMENT_DECLINED. A partir de entonces, el pagador no podrá continuar con el proceso de transacción.
Secuencia de eventos durante la recuperación ante rechazo
- Envíe la solicitud Initiate Browser Payment al motor de pagos con browserPayment.paypal.paymentconfirmation = CONFIRM_AT_PROVIDER.
Se muestra el formulario de pago de PayPal.
- Un pagador inicia sesión en el formulario de pago de PayPal, selecciona el instrumento de pago y luego hace clic en Pagar ahora.
- Envíe la solicitud CONFIRM_BROWSER_PAYMENT para invocar la solicitud Execute Payment de PayPal.
- Si se rechaza el instrumento, PayPal envía la respuesta
INSTRUMENT_DECLINEDa la solicitud Execute Payment.Un pagador tiene tres intentos en total para realizar el pago.
- Después de que el controlador de eventos onApprove reciba la respuesta INSTRUMENT_DECLINED, llame a la función actions.restart() para permitir que un pagador elija un instrumento diferente.
La recuperación ante rechazo no se admite con CONFIRM_AT_MERCHANT (finalizar el pago con 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"
}
Prueba de su integración
Cuando haya finalizado la integración con PayPal, puede probarla utilizando el sandbox de PayPal.
Para comenzar la prueba, cree una cuenta de PayPal y use esas credenciales mientras configura su perfil de negocio con your payment service provider. Asegúrese de utilizar el negocio que no sea de PRUEBA para estas transacciones.
- Utilice los pasos antes mencionados para la integración.
- Asegúrese de enviar la solicitud Payment Options Inquiry para recibir el ID de cliente de your payment service provider en la respuesta.
- Asegúrese de haber configurado la integración de PayPal en Merchant Administration y haber otorgado permiso al tercero para que el motor de pagos realice transacciones en su nombre.