Pagos con tarjeta de regalo

El Mastercard Payment Gateway le permite ofrecer tarjetas de regalo como método de pago a sus pagadores.

Prerrequisitos

  • Debe haber suscrito un acuerdo con un proveedor externo para las tarjetas.
  • Su proveedor de servicios de pago debe configurar su perfil de negocio del Mastercard Payment Gateway mediante los detalles de su cuenta con el proveedor externo.

Incorporación de tarjetas de regalo a su integración

El motor de pagos ofrece tres opciones para integrar tarjetas de regalo a su página de pago:

Tarjetas de regalo mediante Hosted Checkout

Si tiene una integración actual de Hosted Checkout, puede usar Hosted Checkout para verificar los detalles de la tarjeta de regalo.

Puede hacerlo al configurar la interaction.operation=VERIFY en la solicitud Create Checkout Session, Hosted Checkout muestra Tarjeta de regalo como opción de pago para el pagador. Los datos ingresados por el pagador se comprueban mediante los métodos de verificación admitidos por el adquirente configurado.

Usted puede determinar si la operación de verificación se realizó correctamente o no al comparar resultIndicator con successIndicator. Si la interacción no se realizó correctamente, Hosted Checkout muestra un mensaje donde se indica que la verificación no pudo realizarse y se solicita que el pagador vuelva a intentarlo.

Tarjetas de regalo mediante Hosted Session

Si tiene su propia página de pago, entonces puede elegir que la opción de integración Hosted Session haga que el Mastercard Payment Gateway capte de manera segura los detalles de la tarjeta de regalo y los almacene en una sesión de pago.

Código de muestra para recopilar detalles de tarjeta de regalo
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://evopaymentsmexico.gateway.mastercard.com/form/version/57/merchant/<MERCHANTID>/session.js"></script>
<!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE -->
<style id="antiClickjack">body{display:none !important;}</style>
</head>
<body>

<!-- CREATE THE HTML FOR THE PAYMENT PAGE -->

<div>Please enter your Gift Card details:</div>
<div>Card Number: <input type="text" id="gift-card-number" class="input-field" value="" readonly></div>
<div>Pin:<input type="text" id="gift-card-pin" class="input-field" value="" readonly></div>
<div><button id="payButton" onclick="pay();">Pay Now</button></div>

<!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING -->
<script type="text/javascript">
if (self === top) {
    var antiClickjack = document.getElementById("antiClickjack");
    antiClickjack.parentNode.removeChild(antiClickjack);
} else {
    top.location = self.location;
}

PaymentSession.configure({
    fields: {
        // ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A GIFT CARD
        giftCard: {
        	number: "#gift-card-number",
        	pin: "#gift-card-pin",
        }
    },
    //SPECIFY YOUR MITIGATION OPTION HERE
    frameEmbeddingMitigation: ["javascript"],
    callbacks: {
        initialized: function(response) {
            // HANDLE INITIALIZATION RESPONSE
        },
        formSessionUpdate: function(response) {
            // HANDLE RESPONSE FOR UPDATE SESSION
            if (response.status) {
                if ("ok" == response.status) {
                    console.log("Session updated with data: " + response.session.id);
  
                } else if ("fields_in_error" == response.status)  {
  
                    console.log("Session update failed with field errors.");
                    if (response.errors.number) {
                        console.log("Gift card number invalid or missing");
                    }
                    if (response.errors.pin) {
                        console.log("Pin invalid.");
                    }
                } else if ("request_timeout" == response.status)  {
                    console.log("Session update failed with request timeout: " + response.errors.message);
                } else if ("system_error" == response.status)  {
                    console.log("Session update failed with system error: " + response.errors.message);
                }
            } else {
                console.log("Session update failed: " + response);
            }
        }
      }
  });

function pay() {
    // UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS
    PaymentSession.updateSessionFromForm('giftCard', '<localCardBrand>');
}
</script>
</body>
</html>
   
  1. Incluya la biblioteca JavaScript cliente session.js hospedada por el motor de pagos en su página de pago. La ruta a este campo incluye tanto la versión de la API como el identificador del negocio para la sesión.
  2. Cree el HTML para la página de pago que contiene los campos de la tarjeta de regalo.
    Para evitar el envío de datos confidenciales al servidor, asegúrese de que estos campos sean de readonly y NO tengan el atributo name .
  3. Invoque la función PaymentSession.configure(configuration).

    El objeto configuration le permite adosar campos hospedado a su página de pago. Debe proporcionar lo siguiente:

    • session(optional), si no proporciona una, la biblioteca de cliente crea una sesión de pago.
    • selectores de campo para los campos de la tarjeta de regalo, los cuales (cuando se proporcionan) se reemplazan con campos proxy correspondientes incrustados en iFrames hospedados por el Mastercard Payment Gateway. Los campos proxy tendrán la misma apariencia que los campos reemplazados.
    • opciones de mitigación para la prevención de clickjacking

      Clickjacking, también conocido como "ataque de rectificación de UI", se produce cuando un atacante usa varias capas transparentes u opacas para engañar al usuario y lograr que haga clic en un botón o vínculo en otra página cuando intenta hacer clic en la página del primer nivel. Para usar Hosted Session, debe implementar una o más de las siguientes defensas contra ataques de clickjacking.

      Opción de mitigación de marcos Implementación
      javascript Incluya el JavaScript "separador de marcos" en su página de pago.
      x-frame-options su servidor debe devolver un encabezado de respuesta HTTP de opciones X-Frame.
      csp su servidor debe devolver un encabezado de respuesta HTTP de contenido-seguridad-política que contenga una directiva de antecesores de marcos.

      Debe especificar qué defensas se implementan a través del parámetro frameEmbeddingMitigation en la llamada de PaymentSession.configure(configuration). Para obtener información sobre cómo defenderse contra ataques de clickjacking, consulte Referencia de defensa contra clickjacking en el sitio web externo OWASP.

    • devoluciones de llamada para administrar diversos eventos durante la interacción de la Hosted Session.
      • initialized( ): se invoca cuando los campos hospedados se adjuntan a su página de pago.
      • formSessionUpdate( ): se invoca en respuesta a la función PaymentSession.updateSessionFromForm('giftCard', <localCardBrand>) (consulte el paso siguiente)

  4. Invoque PaymentSession.updateSessionFromForm('giftCard', <localCardBrand>) para almacenar los detalles de la tarjeta de regalo recopilados en una sesión de pago. Una vez finalizada la operación, la devolución de llamada formSessionUpdate( ) se invoca con un parámetro de resultado. Debe comprobar el valor result.status para determinar si la operación fue correcta. Consulte Administrar respuestas de devolución de llamada.
  5. Puede usar la sesión de pago devuelta (session.id) para realizar una tokenización o una transacción de pago cuando se requiere. Para obtener más información, consulte Realizar una operación con la sesión.

Referencia de session.js[JavaScript]

Tarjetas de regalo mediante Direct Payment

Si desea tener un control total sobre la interacción de tarjetas de regalo en su página de pago, puede seleccionar la opción Direct Payment.

La opción Tarjetas de regalo es compatible con API en las versiones 31 y posteriores.
Solicitar una autorización o pago usando tarjeta de regalo

Deberá proporcionar los siguientes campos en la solicitud Authorize:

  • sourceOfFunds.type=GIFT_CARD
  • sourceOfFunds.provided.giftCard.number: número de tarjeta de regalo.
  • sourceOfFunds.provided.giftCard.pin: PIN de tarjeta de regalo. (No siempre es obligatorio, dependiendo de la tarjeta de regalo).
  • order.amount: monto que se debe pagar.
  • order.currency: moneda del pago.
  • order.acceptPartialAmount: (opcional) indica si usted está preparado para aceptar la tarjeta para el pago parcial del monto total. El valor predeterminado de este campo es FALSE.

Además de los campos estándar, se devuelven los siguientes campos para una autorización correcta:

  • sourceOfFunds.type: GIFT_CARD, que refleje su solicitud.
  • sourceOfFunds.provided.giftCard.number: número de tarjeta de regalo (con máscara).
  • sourceOfFunds.provided.giftCard.pin: PIN de tarjeta de regalo (totalmente enmascarado).
  • sourceOfFunds.provided.giftCard.scheme: la organización que posee una marca de tarjeta de regalo y define las regulaciones de operación para su uso.
  • sourceOfFunds.provided.giftCard.brand: la marca comercial que se utiliza para describir la tarjeta de regalo que se reconoce y acepta a nivel mundial. Para la mayoría de los tipos de tarjeta principales habrá coincidencia con el nombre de esquema.
  • sourceOfFunds.provided.giftCard.localBrand: la marca comercial que se utiliza para describir una tarjeta de regalo, según lo determinado por el motor de pagos, sobre la base del rango BIN de la tarjeta.
  • availableBalance.funds.amount: el monto a disposición del pagador para gastar usando esta tarjeta de regalo después de este pago. (La entrega de esta información depende del proveedor externo).
  • availableBalance.funds.currency: la moneda del saldo disponible en la tarjeta se expresa como un código alfa ISO 4217, por ejemplo, USD.
  • order.amount: monto aceptado. Tenga en cuenta que este puede ser inferior al monto solicitado, si la tarjeta no tiene fondos suficientes y usted configuró order.acceptPartialAmount=TRUE.
  • transaction.requestedAmount: si la transacción se aprobó parcialmente (response.gatewayCode=PARTIALLY_APPROVED), esta contiene el monto solicitado originalmente.

    Si usted configuró order.acceptPartialAmount=TRUE, transaction.amount y order.amount se configuran en el monto realmente aprobado.
Verificar la tarjeta de regalo

Para verificar que una tarjeta de regalo con el número de tarjeta (y PIN) proporcionado es una tarjeta de regalo válida emitida por el proveedor, envíe una solicitud de APIVERIFY.

Referencia de API de Verify [REST][NVP]

Balance Inquiry

Para consultar el saldo disponible en una tarjeta de regalo, envíe una solicitud de BALANCE_INQUIRY de API. Deberá proporcionar lo siguiente en la solicitud:

  • sourceOfFunds.type=GIFT_CARD
  • sourceOfFunds.provided.card.number: el número de tarjeta de regalo por el que solicita información de saldo.

Referencia de API de Balance Inquiry[REST][NVP]

Administrar aprobaciones parciales

Si usted está preparado para aceptar una aprobación por un monto parcial para una transacción mediante una tarjeta de regalo, debe presentar order.acceptPartialAmount=TRUE en su solicitud. En este caso, usted es responsable de la creación de otra transacción para el saldo pendiente, usando otros medios de pago.

Si usted no está preparado para hacer esto, configure order.acceptPartialAmount=FALSE en su solicitud. Si no hay suficientes fondos disponibles en la tarjeta de regalo, el Mastercard Payment Gateway responderá con response.gatewayCode=INSUFFICIENT_FUNDS.

Referencia de API de Detalles de tarjeta[REST][NVP]

Prueba e inicio de transacciones en producción

Puede probar su integración de tarjetas de regalo mediante su perfil de pruebas del negocio.

Derechos de autor © 2020 Mastercard