- Pautas de integración
- Características soportadas (métodos de pago)
- Implementación de una integración de pago mediante explorador
- PayPal
- Integración de motor de pagos con el SDK de JS de PayPal
Integración de motor de pagos con el SDK de JS de PayPal
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.
Prerrequisitos
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:
- Asegúrese de que your payment service provider haya habilitado PayPal en su perfil de negocio.
- Desde el menú Admin de Merchant Administration, haga clic en Configuración de PayPal y siga las instrucciones para incorporarse a PayPal y activar PayPal para su perfil de negocio. Para actualizar su configuración de PayPal, debe tener los privilegios necesarios.
Agregar un botón inteligente 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.
Paso 1: Crear una sesión
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://banamex.dialectpayments.com/api /rest/version/72/merchant/<your_gateway_merchant_ID>/session |
| Método HTTP | POST |
Paso 2: Actualizar la sesión con los detalles del pedido, la transacción y el pago mediante explorador
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://banamex.dialectpayments.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"
}
}
Paso 3: Incluir el SDK de JS de PayPal del motor de pagos en su página de pago
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://banamex.dialectpayments.com/static/gateway-paypal/1.2.0/gateway-paypal.min.js"></script>
Paso 4: Configurar la interacción de PayPal del motor de pagos
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);
merchantId
El merchantId es necesario para que el motor de pagos pueda determinar correctamente sus opciones de pago.
apiVersion
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.buttonElement
Determina la posición del botón en la página. Es un identificador del elemento DOM donde se representa el botón.
paymentConfirmation
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.
Respuestas de error
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. |
Confirmación de pago
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.
Confirmación del pago 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.
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.
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"
}
Confirmación del pago en el sitio de su tienda
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"
}
}
Recuperación de detalles de la transacción
Puede recuperar los detalles de la transacción para la interacción de PayPal utilizando las siguientes opciones:
- Operaciones Retrieve Order o Retrieve Transaction
- Búsqueda de pedidos y transacciones en Merchant Administration: utilice el número de referencia proporcionado al pagador en el recibo de pago para ver los detalles de la transacción. El número de referencia estará disponible en el pagador y en su extracto bancario. Esto le permite validar aún más la transacción.
Comprender el estado del pedido y de la transacción
browserPayment.paypal.paymentConfirmation es CONFIRM_AT_PROVIDER
| 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.browserPayment.paypal.paymentConfirmation es CONFIRM_AT_MERCHANT
| 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. |
Prueba de su integración
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 de PRUEBA para estas transacciones.
- Utilice su perfil de negocio creado en el sandbox de PayPal.
- Utilice los pasos mencionados anteriormente para la integración.
- 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.