- Pautas de integración
- Características soportadas (métodos de pago)
- Implementación de una integración de pago mediante explorador
- Pagos con PayPal
PayPal
PayPal es un método de pago mediante explorador compatible en Mastercard Gateway. En esta página se describen los detalles de integración específicos de PayPal, incluido el modo de configurar su cuenta comercial PayPal para aceptar pagos mediante el motor de pagos, los requisitos de marca, etc. Le recomendamos leer las pautas de integración para los pagos mediante explorador, antes de crear una integración de PayPal.
Si está integrado para usar PayPal antes de la versión 50 de DirectAPI, haga clic aquí.
Prerrequisitos
Para usar PayPal como método de pago a través de Mastercard Gateway, usted debe tener una cuenta comercial PayPal configurada para el motor de pagos. Para obtener detalles, consulte Configurar su cuenta comercial PayPal.
Para registrarse en una cuenta comercial PayPal, haga clic aquí.
Experiencia de pago de PayPal
Las siguientes secciones le ayudarán a elegir la experiencia de pago de PayPal que sea más adecuada para su sitio.
PayPal permite que sus pagadores realicen pagos en forma rápida y segura en su sitio, lo que les permite usar su cuenta PayPal para pagos y opcionalmente proporcionar información de envío en el sitio. Con PayPal, los pagadores comienzan y terminan el proceso de pagos en su sitio.
El motor de pagos admite dos tipos de flujo de pago de PayPal: Finalizar pedido con PayPal y Pagar con PayPal.
Actualice su versión de SDK a 1.3.0 para ofrecer las opciones de pago Venmo y Pay Later a los compradores. Para obtener más información sobre Venmo y Pay Later, consulte las ofertas de Pagar con Venmo y Pay Later (EE. UU.).
El flujo de Finalizar pedido con PayPal le permite redirigir a un pagador desde su sitio a PayPal mediante la opción Finalizar pedido con PayPal.
- Un pagador ignora el flujo de pago normal y hace el pago usando la información almacenada en su cuenta PayPal.
- PayPal le proporciona el nombre, la dirección de correo electrónico y la dirección de envío desde la cuenta del pagador. Esta acción permite un pago más rápido.
- PayPal recopila la dirección de envío del pagador en PayPal. El pagador puede agregar o editar dicha dirección, si es necesario.
- Después de verificar los detalles del pedido, el pagador selecciona el botón Continuar.
- Se redirige al pagador a su página de pago para la confirmación.
- Si es necesario, puede cambiar el pedido antes de aceptar el pago (por ejemplo, agregando cargos de transporte y envío basados en la dirección devuelta desde PayPal).
Flujo de pago de muestra
El siguiente diagrama describe el flujo de Finalizar pedido con PayPal en que el pagador utiliza la dirección de envío como se almacenó en PayPal. El pagador revisa y confirma el pago en el sitio del negocio.
El flujo de pago es de la siguiente manera:
- Un pagador explora su sitio, selecciona un producto y hace clic en Finalizar pedido con PayPal en la página de pago.
- Cuando el pagador hace clic en el botón Finalizar pedido con PayPal, usted realiza una llamada de
Initiate Browser Paymental motor de pagos y redirige al pagador al URL de PayPal incluido en la respuesta. - El motor de pagos redirige al pagador al sitio Web de PayPal.
- El pagador ingresa a su cuenta PayPal mediante la página de Inicio de sesión de PayPal.
- El pagador especifica la dirección de envío. El pagador puede seleccionar una dirección de envío previamente almacenada en PayPal o ingresar una nueva dirección.
- El pagador selecciona una fuente de financiamiento y continúa con el pago al hacer clic en el botón "Continuar" en PayPal.
- El pagador es redirigido desde PayPal de regreso a su sitio, a través del motor de pagos. Usted recupera los detalles de la transacción, que incluyen la dirección de correo electrónico y la dirección de envío del pagador mediante la operación
Retrieve Transaction. - A continuación, presenta una página de revisión al pagador basada en esta información (por ejemplo, quizás desee agregar cargos de transporte y envío). Cuando el pagador hace clic en el botón "Pagar ahora" para procesar el pago, usted envía una llamada de
Confirm Browser Paymental motor de pagos.El pagador puede elegir actualizar la dirección de envío antes de hacer clic en el botón "Pagar ahora". - El motor de pagos envía una respuesta con los detalles de transacción, que indica el éxito o fracaso de dicha transacción, por tanto, usted puede presentar el estado al pagador.
{
"apiOperation":"INITIATE_BROWSER_PAYMENT",
"browserPayment":{
"operation":"AUTHORIZE",
"paypal":{
"paymentConfirmation":"CONFIRM_AT_MERCHANT"
},
"returnUrl":"Https://test.com"
},
"order":{
"amount":"4.20",
"currency":"USD"
},
"sourceOfFunds":{
"type":"PAYPAL"
}
}
El flujo de Pagar con PayPal le permite al pagador continuar a través del flujo de pago normal, ingresando su información de facturación y envío en el sitio. Cuando se le indica al pagador que elija su método de pago, el pagador elige la opción PayPal ubicada en la página de facturación del sitio junto a otras opciones de pago. A diferencia de la transacción de Finalizar pedido con PayPal, el sitio proporciona la dirección de envío del pagador a PayPal. De manera predeterminada, usted puede elegir no mostrar la dirección de envío y/o desactivar las modificaciones en PayPal. Consulte Mostrar/Anular dirección de envío a continuación para obtener información acerca de cómo implementar esto en su integración de PayPal. El botón "Pagar ahora" permite que el pagador confirme el pago en PayPal antes de ser redirigido de vuelta a su sitio. Esta opción le permite proporcionar una experiencia de pago más rápida al pagador cuando el pagador completa el pago en PayPal.
Flujo de pago de muestra
El diagrama siguiente describe el flujo Pagar con PayPal en que el pagador revisa y confirma el pago en PayPal.
El flujo de pago es de la siguiente manera:
- Un pagador explora su sitio, selecciona un producto y hace clic en PayPal en la página de pago.
- Cuando el pagador hace clic en el botón PayPal, usted realiza una llamada de
Initiate Browser Paymental motor de pagos y redirige al pagador a la URL de PayPal incluida en la respuesta. - El motor de pagos redirige al pagador al sitio Web de PayPal.
- El pagador ingresa a su cuenta PayPal mediante la página de Inicio de sesión de PayPal.
- El pagador revisa los detalles de facturación y confirma el pago haciendo clic en el botón "Pagar ahora" en PayPal.
- El motor de pagos envía una respuesta con los detalles de transacción, que indica el éxito o fracaso de dicha transacción, por tanto, usted puede presentar el estado al pagador.
{
"apiOperation":"INITIATE_BROWSER_PAYMENT",
"browserPayment":{
"operation":"PAY",
"paypal":{
"paymentConfirmation":"CONFIRM_AT_PROVIDER"
},
"returnUrl":"Https://test.com"
},
"order":{
"amount":"4.20",
"currency":"USD"
},
"sourceOfFunds":{
"type":"PAYPAL"
}
}
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.
El botón "Pagar ahora" permite que el pagador confirme el pago en PayPal antes de ser redirigido de vuelta a su sitio. Esta opción le permite proporcionar una experiencia de pago más rápida al pagador cuando el pagador completa el pago en PayPal.
El botón "Continuar" permite redirigir al pagador a su sitio para confirmar el pago después de ver todos los detalles del pedido. 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). Usted también puede incluir otros pasos de pago, por ejemplo: promover ventas en su página Confirmar pedido.
Consulte Confirmación de pago a continuación para obtener detalles acerca de cómo implementar esto en su integración de PayPal.
Dependiendo del flujo de finalizar pedido, Finalizar pedido con PayPal o Pagar con PayPal, puede optar por recopilar la dirección de envío del pagador en su sitio o en PayPal, respectivamente. De manera predeterminada, PayPal recopila la dirección de envío del pagador en PayPal. El pagador puede agregar o editar dicha dirección si es necesario. Usted puede elegir no mostrar la dirección de envío y/o inhabilitar ediciones. Consulte Mostrar/Anular dirección de envío a continuación para obtener información acerca de cómo implementar esto en su integración de PayPal.
Integración de PayPal
PayPal como opción de pago en Hosted Checkout
Si utiliza la página de pago de Mastercard Gateway (Hosted Checkout), se ofrecerá automáticamente PayPal como opción de pago a sus pagadores si your payment service provider ha configurado el vínculo de adquirente de PayPal en su perfil de negocio. Para conocer más detalles, consulte Pagos mediante explorador a través de la integración de Hosted Checkout.
PayPal como opción de pago en su página de pago
Puede agregar PayPal como opción de pago en su página de pago si está integrado a la versión 50 o superior de la API. Debe enviar la solicitud Initiate Browser Payment desde su aplicación del lado del servidor para iniciar la interacción de PayPal.
Se redirige al pagador desde su sitio a PayPal para que inicie sesión y complete los detalles del pago. Para obtener más detalles, consulte PayPal por medio de Direct Payment.
PayPal por medio de Direct Payment
Los siguientes campos en la solicitud de Initiate Browser Payment son específicos para PayPal o tienen uso específico en la integración de PayPal. Para obtener más detalles, consulte Pagos mediante explorador por medio de integración de Direct Payment.
sourceOfFunds.type = PAYPALbrowserPayment.operation=AUTHORIZEoPAY
Con PayPal, los fondos se pueden mantener durante 3 días (período de tramitación) la autorización vence dentro de 3 días desde la fecha en que ocurrió la autorización. Si aún desea capturar los fondos después de 3 días, puede utilizar la operación Update Authorization o iniciar por medio de Merchant Administration.
Por defecto, su cuenta de negocio de PayPal se configura solo para capturas simples. Si desea cambiar la configuración para respaldar varias capturas, contáctese con PayPal.-
Cuando inicie un pago con PayPal, debe especificar si desea que el pagador confirme el pago en PayPal o en su sitio.
Referencia de API de campo Confirmación de pago [REST][NVP]
Si confirma con el proveedor (PayPal), PayPal muestra el botón "Pagar ahora", lo que permite que el pagador confirme el pago en PayPal antes de ser redirigido a su sitio. Debe enviar una solicitud de
Retrieve Transactiona Mastercard Gateway para determinar si el pago se ha realizado correctamente o no.Si confirma en su sitio, PayPal muestra el botón "Continuar", lo que permite que el pagador sea redirigido a su sitio donde el pagador puede confirmar el pago. Debe enviar una solicitud de
Retrieve Transactional motor de pagos para recuperar los detalles y ver si el pagador ha continuado o no con el pago. Si el pagador continúa con el pago en su sitio, debe enviar una llamada deConfirm Browser Paymentpara confirmar el pago con PayPal. La respuesta deConfirm Browser Paymentincluirá información sobre el éxito o fracaso del pago.Referencia de API de Confirm Browser Payment [REST][NVP]
En ambos casos, si el pago es exitoso, la operación Retrieve Transaction devuelve:
- la dirección de correo electrónico de la cuenta PayPal del pagador;
- el nombre del titular de la cuenta en la cuenta PayPal del pagador;
- el ID del pagador asociado con la cuenta de PayPal del pagador;
- los detalles de la dirección de envío.
{ "apiOperation":"CONFIRM_BROWSER_PAYMENT", "order":{ "amount":"4.20", "currency":"USD" } } -
Usted puede administrar la forma en que el pagador le proporciona la dirección de envío al usar dos campos:
browserPayment.paypal.displayShippingAddress: cuando se configura como true (predeterminado), la dirección de envío se muestra en PayPal.Referencia de API de campo Mostrar dirección de envío [REST][NVP]
browserPayment.paypal.overrideShippingAddress: cuando se configura como true (predeterminado), el pagador puede cambiar la dirección de envío en PayPal.Referencia de API de campo Anular dirección de envío [REST][NVP]
Por defecto, PayPal recopila por usted la dirección de envío del pagador en PayPal. Si elige recopilar la dirección de envío del pagador en su sitio y no desea que PayPal muestre la dirección de envío al pagador, debe configurar como false la opción
browserPayment.paypal.displayShippingAddress. Esto también se aplica cuando no se requiere la dirección de envío en un pedido (por ejemplo, cuando solo se trata de productos digitales).El motor de pagos siempre devolverá la dirección de envío en la respuesta de
Retrieve Transactionsi se proporcionó la dirección en la solicitud deInitiate Browser Paymento si la opciónbrowserPayment.paypal.displayShippingAddressestá configurada como true.Debe usar la dirección de envío incluida en la respuesta de la transacción en el caso de que el pagador haya cambiado la dirección de envío en PayPal. Tenga en cuenta que PayPal valida combinaciones de ciudad, estado y código postal para direcciones de envío de EE. UU. -
Es posible especificar los detalles de producto de línea en la solicitud de
Initiate Browser Paymentpara proporcionar todos los detalles del pedido a los pagadores antes de que ellos confirmen el pago. La investigación sobre consumidores muestra que existen más compradores que completan sus compras cuando ven los productos individuales y otros detalles de un pedido durante un pago con PayPal. Por consiguiente, se le recomienda que proporcione la información del pedido cuando inicie el pago con PayPal para motivar a los pagadores a que continúen con el pago en vez de abandonarlo.Los productos de línea se consideran como proporcionados si se especifica el nombre o el precio unitario del producto. Para obtener más información sobre los detalles de producto de línea, consulte Datos de producto de línea.
Cómo interpretar el resultado de la transacción
La tabla siguiente muestra los códigos de respuesta de transacción para los posibles escenarios que puede encontrar después de iniciar un pago mediante explorador.
Respuesta de Initiate Browser Payment |
Qué significa esto... |
|---|---|
response.gatewayCode=SUBMITTEDresult=SUCCESS |
Redirigir al pagador utilizando la URL proporcionada en la respuesta. |
response.gatewayCode=SUBMITTEDresult=FAILURE or PENDING or UNKNOWN |
Envíe otra solicitud de INITIATE_BROWSER_PAYMENT. |
Respuesta de Retrieve Transaction/Retrieve Order |
Qué significa esto... |
response.gatewayCode=APPROVEDresult=SUCCESS |
El pago se realizó correctamente. |
response.gatewayCode=PENDINGresult=PENDING |
El pago tiene una revisión pendiente en el sistema de PayPal. Consulte Pagos pendientes. |
response.gatewayCode=CANCELLEDresult=FAILURE |
El pagador canceló la interacción para este pago. Ofrezca al pagador la opción de probar otro método de pago. |
response.gatewayCode=DECLINED or INSUFFICIENT_FUNDS or NOT_SUPPORTEDresult=FAILURE |
El pago fue rechazado por PayPal. |
response.gatewayCode=ACQUIRER_SYSTEM_ERRORresult=FAILURE |
El adquirente no pudo procesar la transacción. Puede consultar con el adquirente el motivo del error del pago, o bien puede intentar RETRIEVE_TRANSACTION de nuevo. También, puede ofrecer al pagador la opción de probar otro método de pago. |
response.gatewayCode=SYSTEM_ERRORresult=FAILURE |
El motor de pagos no pudo procesar la transacción. |
response.gatewayCode=TIMED_OUTresult=FAILURE |
La interacción entre el pagador y el sistema de PayPal no se completó correctamente, por ejemplo, el motor de pagos no recibió una redirección del explorador del pagador proveniente del negocio en un plazo de 24 horas, o bien el motor de pagos no pudo recuperar los detalles de la interacción entre el pagador y el sistema de PayPal, por ende el pago quedó incompleto. |
response.gatewayCode=UNKNOWNresult=UNKNOWN |
El motor de pagos no pudo averiguar si el pago se realizó correctamente o no. |
Actualizaciones de autorización
Puede actualizar el período de tramitación de la autorización o aumentar los montos de autorización para transacciones de autorización de PayPal válidas, utilizando la operación Update Authorization o mediante Merchant Administration. Para esto, your payment service provider debe habilitar el privilegio "Update Authorization" en su perfil del negocio. Para obtener más información, consulte Update Authorization.
Se recomienda que actualice una autorización después de los 3 días iniciales (período de tramitación) para asegurarse de que los fondos sigan disponibles. Un pago reautorizado tiene un nuevo período de tramitación de 3 días. El período de tramitación de 3 días se puede actualizar como máximo dentro del período de validez de 29 días.
Se puede actualizar una autorización una vez para un máximo del 115 % o 75 USD del monto autorizado originalmente.
Capturas, reembolsos y anulaciones
Para los pagos con PayPal, puede capturar el monto autorizado de manera parcial o total del monto autorizado originalmente utilizando la operación Capture o por medio de Merchant Administration.
Puede reembolsar de manera parcial o total pagos procesados por medio de PayPal para transacciones Pay y Capture. Puede enviar solicitudes de reembolso utilizando la operación Refund o mediante Merchant Administration.
Puede anular cualquier transacción autorizada si los intentos de captura han fallado o puede reembolsar una transacción Pay para revertir el pago. Puede enviar la solicitud de Void o Refund utilizando la operación API, Void y Refund o a través de Merchant Administration.
Pagos pendientes
El motor de pagos puede devolver el estado PENDING en la respuesta de la transacción. Por ejemplo, si la transacción actualmente está bajo evaluación de riesgos en PayPal. Si el estado es pendiente y usted configuró sus propios filtros de administración de fraudes, debería iniciar sesión en su cuenta comercial PayPal y revisar el pago. Cuando PayPal actualice el estado de una transacción pendiente, se lo notificará al motor de pagos.
Acuerdo de facturación y pagos recurrentes
Si utiliza Finalizar pedido con PayPal o Pagar con PayPal, puede configurar un acuerdo de facturación para un pagador, lo que permite iniciar una transacción de referencia (pagos por suscripción/recurrentes o a demanda) sobre este acuerdo de facturación sin consentimiento adicional del pagador. Para obtener más información, consulte Acuerdo de facturación y pagos recurrentes.
Configurar su integración de PayPal
Para procesar transacciones a través de PayPal, debe otorgar permiso al motor de pagos para enviar solicitudes de transacciones a PayPal en su nombre. Para otorgar permiso a terceros, debe iniciar sesión en el portal de Merchant Administration. En la página de configuración de PayPal, puede ver los vínculos de adquirente del negocio de PayPal que your payment service provider configuró para usted. Si no ha otorgado permiso al tercero en el vínculo de adquirente, el campo ID de cuenta permanece vacío. Por lo tanto, debe otorgar permiso al motor de pagos para que este pueda realizar llamadas de API en su nombre.
Para otorgar permisos de terceros para las API de PayPal con una nueva cuenta de correo electrónico:
- Para otorgar el permiso de terceros para un vínculo de adquirente específico, seleccione Habilitar.
- Ingrese los detalles necesarios en la página de PayPal y, a continuación, seleccione Siguiente.
- Ingrese los detalles necesarios y, luego, seleccione las casillas de verificación Acuerdo de usuario y Declaración de privacidad.
- Seleccione Aceptar y crear una cuenta.
- Ingrese la información relacionada con la empresa y luego haga clic en Siguiente.
- Ingrese la información relacionada con el usuario y luego haga clic en Enviar.
La página de confirmación de registro muestra las instrucciones para activar su cuenta de PayPal.
- Active su cuenta de PayPal según las instrucciones enviadas a la dirección de correo electrónico que indicó en el momento de registrarse.
- Siga las instrucciones en la pantalla para volver a la página de Merchant Administration.
Se conceden los permisos de terceros necesarios para el vínculo de adquirente de PayPal específico. El estado se habilita y se muestra el ID de la cuenta de PayPal.
- Para revocar el permiso de terceros, seleccione Deshabilitar y para actualizar cualquier información, seleccione Actualizar.
Si el permiso de terceros falla debido a cualquier problema, se muestra un mensaje de error.
Para otorgar permisos de terceros para las API de PayPal con una cuenta de correo electrónico registrada:
- Para otorgar el permiso de terceros para un vínculo de adquirente específico, seleccione Habilitar.
- Ingrese los detalles necesarios en la página de PayPal y, a continuación, seleccione Siguiente.
- Ingrese sus credenciales y luego seleccione Iniciar sesión.
Se ha registrado e integrado correctamente en PayPal.
- Siga las instrucciones en la pantalla para volver a la página de Merchant Administration.
Se conceden los permisos de terceros necesarios para el vínculo de adquirente de PayPal específico. El estado se habilita y se muestra el ID de la cuenta de PayPal.
- Para revocar el permiso de terceros, seleccione Deshabilitar y para actualizar cualquier información, seleccione Actualizar.
Si el permiso de terceros falla debido a cualquier problema, se muestra un mensaje de error.
Mejor protección para el vendedor
Puede enviar datos adicionales del pagador en la solicitud Initiate Browser Payment y en las solicitudes Pay o Authorize posteriores, después de realizar el Tokenize Browser Payment para permitir que PayPal realice una evaluación de riesgos de la transacción antes de que esta se procese.
PayPal utiliza los datos de los siguientes campos para realizar una evaluación de la administración de riesgos previa a la transacción:
device.fingerprint: identificador único para el dispositivo que se puede generar utilizando la biblioteca Javascript de PayPal FraudNet. Esto permite a PayPal realizar una evaluación de riesgos de la transacción.risk.custom: en este campo puede proporcionar datos adicionales sobre el pago. Debe tener un acuerdo con PayPal sobre los valores que desea proporcionar. Por ejemplo,risk.custom.headOfficeLocation=Londres RU.sourceOfFunds.token: el token que identifica los detalles del acuerdo de facturación (recibidos de PayPal) en el motor de pagos. Puede utilizar este ID de token para los pagos únicos y recurrentes. Para obtener más información, consulte Acuerdo de facturación y pagos recurrentes.Para el pago directo, lasourceOfFundses Paypal.
Reembolso excesivo
Los reembolsos excesivos deben estar habilitados en el sitio de PayPal. Puede capturar el monto de exceso autorizado por medio de la solicitud Capture o por medio de Merchant Administration.
Se permite una captura en exceso de hasta el 115 % de la transacción autorizada original. Puede devolver de manera parcial o total los pagos en exceso procesados por medio de PayPal para las transacciones Pay y Capture.
Puede enviar solicitudes de reembolso utilizando la operación Refund o mediante Merchant Administration.
Para un reembolso excesivo, incluya un monto que supere el monto de la transacción original. Para reembolsar en exceso del monto capturado, asegúrese de estar habilitado para los reembolsos excesivos en su perfil de negocio de PayPal.
Si su perfil de PayPal está habilitado para los reembolsos excesivos, asegúrese de configurar su perfil de negocio de Mastercard Gateway para dichos reembolsos.
Prueba de su integración
El Mastercard Gateway proporciona un emulador de PayPal que permite probar su integración para usar la funcionalidad de PayPal a través del motor de pagos.