Saltar al contenido principal

Solo tarjeta (iframe)

Introducción​

Este componente visual te permitirá realizar una transacción en dos partes. Primero capturamos la tarjeta generando un token temporal llamado request_id.

El segundo paso consisitirá en utilizar el API en modo server-to-server para ejecutar una transacción de todas las disponibles. En esta documentación deberás utilizar el parámetro fastpay para recuperar la información original del token además de indicar la operación a realizar.

Captura de tarjeta​

Con este método de integración podrás capturar de manera segura la tarjeta y posteriormente realizar cualquier tipo de operación soportada por el API. En ningún momento los datos de tarjeta pasarán por tu servidor, de esta forma se asegura el correcto cumplimiento de PCI DSS.

El comercio deberá incluir un archivo JavaScript en la web para el entorno de sandbox:

sandbox
<script type="text/javascript" src="https://sandbox.sipay.es/fpay/v1/static/bundle/fastpay.js"></script>

Y sustituirlo por este para el entorno de producción:

live
<script type="text/javascript" src="https://live.sipay.es/fpay/v1/static/bundle/fastpay.js"></script>
tip

Se recomienda incluir el fichero javascript en la etiqueta <head>.

Adicionalmente no olvides incluir la siguiente sentencia en la sección <head> de la página, para escalar el contenido y hacerlo adaptable a diferentes dispositivos.

<meta name="viewport" content="width=device-width, initial-scale=1">

Para hacer uso del script se deberá crear un botón (class="fastpay-btn") en la web. Este botón tiene unos atributos obligatorios:

  • data-key(string, required): Identificador del API proporcionado por Sipay.
  • data-amount(string, required): Importe de la transacción en formato número entero, ejemplos: data-amount="1025" sería 10.25 € (si currency = EUR), data-amount="5" sería 0.05€ (si currency = EUR).
  • data-currency: Tipo de moneda. Código ISO 4217 de tres letras. Para más opciones ver la ISO 4217 data-currency="EUR".
  • data-template(enum[string]): Plantilla a renderizar. Puede ver las opciones disponibles en esta misma página de documentación.

El boton puede renderizar tres tipos de plantillas que se configuran con el atributo data-template. Se puede omitir esta opción para mostrar la plantilla clásica por defecto.

  • v1(clásica).
  • v2.
  • v3.
  • embedded.

Dependiendo de la plantilla, podremos personalizar distintos atributos.

Para gestionar los datos de respuesta del iframe podremos utilizar uno de estos dos atributos excluyentes:

  • data-callback(string): Función de JavaScript que se ejecutará al terminar la captura de tarjeta (Ver respuestas).
  • data-redirect(string): URL a la cual se redirigirá la operación después de recibir realizar la captura de tarjeta. Se le agregará el token recibido por el servicio de Sipay como query string https://example.es/commerce/fpay?request_id=1234567890 (Ver respuestas).

Aparte de estos campos obligatorios existen otros atributos que permiten su personalización:

  • data-lang(enum[string]): Idioma para los textos no editables. Por defeto se mostrarán en castellano:
    • "es": Mostrará los textos en castellano.
    • "en": Mostrará los textos en inglés.
  • data-notab(string): Para bloquear la ventana emergente añadir el atributo en el código html => data-notab = "1".
  • data-finish_cb (string): Función opcional a ejecutar al terminar la transacción, se ejecuta antes de data-callback y se utiliza para reflejar los cambios en el botón al terminar una operación (ver personalización).
  • data-autosave(string): Utilizaremos true para ocultar el botón de recuérdame y el valor false para mostrarlo. El valor por defecto es false.
  • data-remember(string): Cuando tengamos activado autosave, podremos elegir si queremos el botón tipo 'slide' o 'checkbox'. Por defecto tiene el valor de slide.
  • data-remembertext(string): Si tenemos activado autosave, podremos elegir el texto personalizado para el 'recuérdame'.
  • data-paymentbutton(string): Permite modificar el literal del botón de pago.

Plantilla clásica (v1)​

Se comportará como un pop-up pero sin abrir ninguna ventana nueva. De esta forma el consumidor no abandonará la web del comercio mientras introduce sus datos. Puede ver el comportamiento de tipo pop-up en este enlace y modificarlo en este otro.

Podemos configurar los siguientes atributos:

  • data-notab(string): Permite modificar el comportamiento estilo pop-up al añadir el atributo con el valor "1". Se comportará como un componente embebido en el contenedor html asignado.

  • data-finish_cb (string): Función opcional a ejecutar al terminar la captura de tarjeta. Se ejecuta antes de data-callback y se utiliza para reflejar los cambios en el botón al terminar una operación (ver personalización).

  • data-hiddenprice(string): Utilizaremos true para ocultar el precio dentro del botón de pago. En caso contrario el valor false permitirá mostrar el importe en el propio botón. El valor por defecto es false.

  • data-autosave(string): Utilizaremos true para ocultar el botón de recuérdame y el valor false para mostrarlo. El valor por defecto es false.

  • data-remember(string): Cuando tengamos activado autosave, podremos elegir si queremos el botón tipo 'slide' o 'checkbox'. Por defecto tiene el valor de slide.

  • data-remembertext(string): Si tenemos activado autosave, podremos elegir el texto personalizado para el 'recuérdame'.

  • data-profile(string): Podremos indicar un perfil de bloqueo de tarjetas por BIN de tarjeta. Tendrá que hablar con su integrador para realizar este bloqueo.

  • data-theme(string): Influye en como se mostrará el formulario de introducción de datos de tarjeta (default="standard"). Se puede omitir esta opción y mostrará una plantilla azul por defecto.

    • standard
    • red
    • grey

  • data-logo-style(enum[string]): Estilo del logo mostrado en el iframe (default=circle).

    • circle
    • square
    • rectangle

    Es posible modificar el tamaño y la transparencia de logotipo añadiendo al atributo la cadena “large”. “small” o “transparent”. A continuación se muestran los valores posibles para un ejemplo con “circle”:

    • circle_transparent
    • circle_small
    • circle_small_transparent
    • circle_large
    • circle_large_transparent

  • data-logo-url(string): URL de la imágen del logo. Preferiblemente de 75x75 o 150x75 en caso de estilo de logo rectangular data-logo-style="rectangle".

  • data-business-title(string): Ideal para indicar el nombre de tu marca o negocio, por ejemplo “TextoTítulo”. Si no se especifica, no muestra título.

  • data-description(string): Ideal para indicar la descripción de la compra. Si no se especifica, no muestra descripción.

El siguiente ejemplo muestra el mismo comportamiento anterior pero esta vez utilizando una función de JavaScript para gestionar el callback:

Plantilla (v2)​

Con la plantilla dinámica( data-template="v2"), a parte de los atributos que se podían configurar con la plantilla clásica, tendremos los siguientes:

  • data-carholdername(string): determina si se renderiza o no el campo para introducir el nombre del propietario de la tarjeta. Utilizando el valor true mostrará el campo.
  • data-header(string): Mostrará o no la cabecera del formulario de pago.
  • data-autosave(string): determina si se renderiza o no el botón que habilita la función “Recuérdame”.
    • false: mostrará el botón “Recuérdame”.
    • true: desaparecerá el texto y opción de guardado de tarjeta y se devolverá data.payload.consent como true. Para más información consultar “Activación y personalización del botón "Recuérdame"”.
  • data-remember(enum[string]): Permite seleccionar si se quiere renderizar un slider (slide) o un cuadro de selección (checkbox) para la función “Recuérdame”.
    • slide
    • checkbox
  • data-remembertext(string): Permite modificar el literal del botón "Recuérdame". Si customiza el literal del botón de guardado de tarjeta Sipay no mostrará su advertencia legal, por lo que deberá hacerlo el cliente.
  • data-sipay(string): Será posible mostrar (true) o no (false) el logotipo de Sipay.
  • data-paymentbutton(string): permite modificar el literal del botón de pago.
  • data-hiddenprice(string): Utilizaremos true para ocultar el precio dentro del botón de pago. En caso contrario el valor false permitirá mostrar el importe en el propio botón. El valor por defecto es false.

Plantilla (v3)​

Inspirada en otro diseño para embeberlo en su página web, podrá utilizar los mismos parámeros que la v2.

Embebido​

Plantilla optimizada para incruster en procesos de captura de tarjeta. Revisa los parámetros de personalización para adaptarlo a tus necesidades.

Respuestas​

Callback - atributo: data-callback​

La respuesta del iframe o ventana de captura de tarjeta consiste un mensaje en formato JSON que contiene un identificador de la transacción identificado como request_id. Deberá utilizarse para finalizar el proceso de cobro.

Este JSON tiene la siguiente estructura:

{
    "type": "success",
    "code": "0",
    "detail": "tokenization done successfully",
    "description": "Information saved and tokenized",
    "request_id": "ae8893641c7b4d5486f99279f16bb31b",
    "uuid": "04ebf843-6ac4-4fdc-aa1a-bc876c140dde",
    "payload":{
        "consent":false,
        "cadholder_name":null,
        "expiration":"**/**",
        "pan":"**** **** **** ****"
    }
}

Donde:

  • type (string) : tipo de respuesta
  • uuid (string) : id unico de petición
  • detail (string) : detalle de respuesta
  • description (string) : descripción de respuesta
  • code (string) : código de resultado de operación
  • payload (json) : respuesta en json
    • consent (string): respuesta botón "Recúerdame". Valor true cuando el usuario activa el botón
    • cardholder_name(string): nombre del propietario de la tarjeta introducido en el formulario
    • expiration(string): fecha de caducidad de la tarjeta (mes/año)
    • pan(string): número de la tarjeta enmascarado
  • request_id : token temporal de captura de tarjeta. Es necesario para poder realizar cualquier tipo de operación adicional (venta, tokenización, ...). Tiene una duración de cinco minutos.
ejemplo de función JavaScript para callback
function callbackFunction(data){
 alert(data)
}

Redirect - atributo: data-redirect​

En este caso el request_id se concatenará a la URL indicada en el atributo data-redirect en formato QueryString y con la clave request_id. Si utilizáramos de ejemplo https://httpbin.org/get como URL, una vez capturada la tarjeta nos llevaría a:

https://httpbin.org/get?request_id=12345677890

Tu código debería capturar este valor y terminar la operación server-to-server con nuestro API.

Personalización​

Podemos personalizar la apariencia del botón utilizando CSS estándar:

.fastpay-btn img {
  display: none;
}

.fastpay-btn {
  border: 1px solid black !important;
  background: #eaeaea !important;
  padding: 2px 5px;
}

Si oculta el botón mostrado por defecto con este CSS:

.fastpay-btn img {
  display: none;
}

podrás emplear esta función de JavaScript para cargar el formulario en el momento que necesites:

document.addEventListener("DOMContentLoaded", function () {
  document.querySelector(".fastpay-btn").click();
});

Ejemplo completo:

Plantilla V2​

El estilo de la hoja de pago puede ser modificado vía JavaScript, esto se hace de la siguiente manera:

Fastpay.customize({
  colors: {
    title: '#000000',
    description: '#ffffff',
    header_line: '#08b041',
    inputs_lines: '#08b041',
    icon: '#6f6f6f',
    info: '#08b041',
    button: '#08b041',
    cvv_info: '#6f6f6f',
    header_color: '#08b041'
  }
});

Plantilla embedded​

Para la plantilla "embedded" (data-template="embedded"), los atributos que podemos modificar son los siguientes:

Fastpay.customize({
  colors: {
    inputs_lines: '#08b041',
    info: '#08b041',
    button: '#08b041',
    cvv_info: '#08b041',
  }
});

Además, se permite el uso del parámetro data-finish_cb en el botón para personalizar como se maneja el botón en base a la respuesta. Este callback recibirá como parámetros el objeto del botón y la respuesta. El objeto del botón contendrá el elemento del DOM en un parámetro "el".

Ejemplo de uso:

function finishcb(button, response){
 button.el.innerText = "Finishcb:PagoRealizado"; 
}

Uso del script en entornos asíncronos​

En caso de que necesitemos hacer uso del script en entornos en los que el botón no se haya cargado al inicio o requiramos más flexibilidad a la hora de integrar, podemos utilizar un proceso manual estableciendo una variable window.DONT_AUTOLOAD_FPAY

DONT_AUTOLOAD_FPAY = true;

Disponemos de un objeto Fastpay que expone el siguiente método para cargar todos los botones disponibles:

  • loadAll: Este método automáticamente carga todos los botones con .fastpay-btn, incluso si tenemos establecido DONT_AUTOLOAD_FPAY = true;

Y los siguientes métodos para cargar botones individualmente:

  • loadStyles: Este método añade el CSS de FastPay a la página, debe llamarse si se ha establecido DONT_AUTOLOAD_FPAY y no se va a hacer una llamada a loadAll.
  • loadButton: Este método recibe un elemento DOM con el botón sobre el que se va a inicializar fastpay y configura la apertura de Fastpay al hacer click en el botón.
  • addButton: Este método recibe un elemento DOM con el botón sobre el que se va a inicializar FastPay y cambia el estilo del botón para adecuarse al estilo de FastPay.

Ejemplo de uso para cargar todos los botones:

Fastpay.loadAll()

Ejemplo de uso para cargar un solo botón

Fastpay.loadStyles()
FastPay.loadButton(document.getElementById('fastpay_button_1'))
FastPay.addButton(document.getElementById('fastpay_button_1'))