Integration Types
Otras características
Card Payments
Mobile Wallets
Alternative Payment Methods
Resources
Esta guía describe cómo agregar el botón inteligente de PayPal a su página de pago mediante la integración con el SDK de JavaScript de PayPal proporcionado por el motor de pagos.
Para ofrecer el botón inteligente de PayPal como opción de pago a sus pagadores mediante el SDK de JavaScript de PayPal del motor de pagos:
Siga los pasos que se describen a continuación para crear su integración con el SDK de JavaScript de PayPal del motor de pagos.
El SDK de JavaScript de PayPal del motor de pagos utiliza la autenticación basada en sesión. Cree una sesión para actualizar los campos de solicitud y los valores que desee almacenar.
Para crear una sesión, envíe la solicitud Create Session desde su aplicación del lado del servidor. La respuesta devuelve un ID de sesión que debe utilizar en los pasos siguientes para hacer referencia a esta sesión.
URL | https://evopaymentsmexico.gateway.mastercard.com/api /rest/version/72/merchant/<your_gateway_merchant_ID>/session |
Método HTTP | POST |
Actualice la sesión con el monto y la moneda del pedido enviando la solicitud Update Session desde su aplicación del lado del servidor.
Actualice la sesión con al menos la ID del pedido, la ID de la transacción, el monto del pedido, la moneda y los detalles de pago mediante explorador (Confirmación de pago) enviando la solicitud Update Session desde su aplicación del lado del servidor.
browserPayment.returnUrl
es opcional, ya que no se necesita para que la interacción del botón inteligente de PayPal funcione.URL | https://evopaymentsmexico.gateway.mastercard.com/api /rest/version/72/merchant/<your_gateway_merchant_ID>/session>/<your_session_ID> |
Método HTTP | PUT |
{ "apiOperation": "UPDATE_SESSION", "browserPayment": { "operation": "PAY", "paypal": { "paymentConfirmation": "CONFIRM_AT_PROVIDER" } }, "order": { "amount": "679.99", "currency": "USD" }, "sourceOfFunds": { "type": "PAYPAL" } }
Incluya el SDK de JavaScript de PayPal del motor de pagos (gateway-paypal.js) en su página de pago agregando un elemento script
dentro del elemento head. Al hacerlo, se coloca el objeto GatewayPaypal
en el espacio de nombres de la ventana.
<script type="text/javascript" src="https://evopaymentsmexico.gateway.mastercard.com/static/gateway-paypal/1.2.0/gateway-paypal.min.js"></script>
Al cargar su página de pago, inicie la interacción de PayPal invocando GatewayPaypal.configure (config, errorCallback, completeCallback, cancelCallback). Al hacerlo, se redirigirá su página de pago a configure.html del método de PayPal del motor de pagos.
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);
El merchantId
es necesario para que el motor de pagos pueda determinar correctamente sus opciones de pago.
El SDK de apiVersion
debe coincidir con la versión que utilice al enviar la solicitud Create Session. Por ejemplo, al crear una sesión, si utiliza la apiVersion
61, asegúrese de usar la misma apiVersion
para todas las demás configuraciones relacionadas con esta. Si hay una discrepancia entre apiVersion
, la operación fallará.
apiVersion
en config() es 61. Si no proporciona el valor para apiVersion
, se adopta el valor predeterminado.Determina la posición del botón en la página. Es un identificador del elemento DOM donde se representa el botón.
Indica en qué parte del flujo de pago desea que el pagador confirme el pago, puede ser en el sitio web de usted o en PayPal.
La llamada GatewayPaypal.configure()
puede devolver las siguientes respuestas de error.
response.cause | resp.explanation | Acción requerida |
---|---|---|
Error | Falta un argumento: Merchant ID, Hosted Session ID, Payment Confirmation, Button Element y tres funciones de devolución de llamada son argumentos necesarios para el método configure(). | Corrija su integración. Proporcione todos los campos de solicitud obligatorios. |
Error |
|
Corrija la integración proporcionando las funciones correctas. |
Error | La versión de API debe ser <MIN_VERSION> o superior. | Corrija su integración. Establezca apiVersion en 60 o superior. |
Con los flujos de pago de Finalizar pedido con PayPal y Pagar con PayPal, puede optar por visualizar Pagar ahora o el botón Continuar en PayPal.
Al enviar CONFIRM_AT_PROVIDER
, se muestra el botón Pagar ahora en la ventana modal de PayPal. El botón Pagar ahora permite al pagador confirmar el pago en la ventana modal de PayPal. Esta opción le permite proporcionar una experiencia de pago más rápida al pagador cuando el pagador completa el pago en PayPal.
En caso de que el pagador confirme el pago en el sitio de PayPal, puede enviar una solicitud Retrieve Transaction o Retrieve Order al motor de pagos para verificar el resultado de la transacción. A continuación, puede mostrar la página Pago realizado con los últimos detalles.
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.
Se muestra el formulario de pago de PayPal.
INSTRUMENT_DECLINED
a la solicitud Execute Payment.
Un pagador tiene tres intentos en total para realizar el pago.
const restartPaymentOnInstrumentDeclined = (resp, actions) => { if (isInstrumentDeclined(resp)) { return actions.restart(); } else { gatewaySuccessCallbackBP(resp); } }
{ "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" }
{ "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" }
Al enviar CONFIRM_AT_MERCHANT
, el botón Continuar se muestra en la ventana modal de PayPal.
El botón Continuar permite que el pagador sea redirigido al sitio de su tienda para confirmar el pago después de finalizar la interacción con la ventana modal de PayPal. Esta opción le permite cambiar el pedido, si es necesario, antes de aceptar el pago (por ejemplo: al agregar cargos de transporte y envío basados en la dirección devuelta desde PayPal).
En caso de que el pagador confirme el pago en su sitio, es decir, utilice CONFIRM_AT_MERCHANT
como confirmación de pago, se mostrará la página de confirmación de pago al pagador. Puede enviar la solicitud Retrieve Transaction o Retrieve Order al motor de pagos para verificar el resultado de la transacción. Cuando el pagador decide continuar con el pago, se debe enviar CONFIRM_BROWSER_PAYMENT
al motor de pagos para finalizar el pago. A continuación, puede mostrar la página Pago realizado con los últimos detalles. Puede utilizar esta operación para actualizar los atributos del pago, como los costos de envío, para reflejar los detalles de envío seleccionados por el pagador en la interfaz de usuario de PayPal.
{ "apiOperation": "CONFIRM_BROWSER_PAYMENT", "order": { "amount": "779.99", "currency": "USD", "shippingAndHandlingAmount": "100.00" } }
Puede recuperar los detalles de la transacción para la interacción de PayPal utilizando las siguientes opciones:
Estado de interacción de pago mediante explorador | Código de respuesta del motor de pagos de la transacción | Estado del pedido | Descripción |
---|---|---|---|
browserPayment.interaction.status=INITIATED | response.gatewayCode=SUBMITTED | order.status=INITIATED | Se ha enviado la transacción mediante la operación INITIATE_BROWSER_PAYMENT. |
browserPayment.interaction.status=COMPLETED | response.gatewayCode=APPROVED | order.status=CAPTURED | El pagador ha hecho clic en Pagar ahora y se ha enviado la solicitud CONFIRM_BROWSER_PAYMENT. |
INSTRUMENT_DECLINED
entonces el estado de response.gatewayCode será SUBMITTED y el de order.status será INITIATED. Este estado seguirá siendo el mismo si el instrumento se rechaza en los dos primeros intentos de realizar el pago. Si el instrumento también se rechaza en el tercer intento, la transacción se rechazará y el estado de la respuesta de .gatewayCode y order.status cambiará a DECLINED y FAILED respectivamente.Estado de interacción de pago mediante explorador | Código de respuesta del motor de pagos de la transacción | Estado del pedido | Descripción |
---|---|---|---|
browserPayment.interaction.status=INITIATED | response.gatewayCode=SUBMITTED | order.status=INITIATED | Se ha enviado la transacción mediante la operación INITIATE_BROWSER_PAYMENT. |
browserPayment.interaction.status=RETURNED_TO_MERCHANT | response.gatewayCode=SUBMITTED | order.status=INITIATED | El pagador ha hecho clic en Continuar en PayPal y se ha enviado la operación UPDATE_BROWSER_PAYMENT |
browserPayment.interaction.status=COMPLETED | response.gatewayCode=APPROVED | order.status=CAPTURED | Se ha enviado la operación CONFIRM_BROWSER_PAYMENT. |
Cuando haya finalizado la integración con el motor de pagos de 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 TEST para estas transacciones.