Formulario incrustado: prueba rápida

Esta página ofrece un ejemplo de integración de un formulario de pago seguro, en 3 simples pasos.

Para obtener una guía de integración más completa (o para la integración desde un sitio en JavaScript), consulte: Primeros pasos: Pago simple

1. Inicializar el formulario

Cuando un comprador finaliza su compra en su sitio, usted debe validar su transacción en su servidor de vendedor comprobando, en particular, el monto, la moneda, el contenido del carrito, etc.

Tras estos controles, su servidor de vendedor debe llamar el Servicio Web Charge/CreatePayment para inicializar la transacción.

En respuesta, su servidor de vendedor recupera un formToken, objeto cifrado que permite inicializar el formulario incrustado con los datos de la transacción y de la configuración de la tienda.

{
    "amount":   990,
    "currency": "EUR",
    "orderId":  "myOrderId-999999",
    "customer": {
        "email": "sample@example.com"
    }
}
    
{
    "amount":   ,
    "currency": "",
    "orderId":  "myOrderId-999999",
    "more": "parameters",
    "customer": {
        "email": "sample@example.com"
    }
}
    
{
    "amount":   ,
    "currency": "",
    "orderId":  "myOrderId-999999",
    "more": "parameters",
    "customer": {
        "email": "sample@example.com"
    }
}
    
{
    "amount":   ,
    "currency": "",
    "orderId":  "myOrderId-999999",
    "more": "parameters",
    "customer": {
        "email": "sample@example.com"
    }
}
    
{
    "amount":   ,
    "currency": "",
    "orderId":  "myOrderId-999999",
    "more": "parameters",
    "customer": {
        "email": "sample@example.com"
    }
}
    
/**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * I create a formToken
 */
$store = array("amount" => 250, 
"currency" => "EUR", 
"orderId" => uniqid("MyOrderId"),
"customer" => array(
  "email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];

?>

    
/**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * I create a formToken
 */
$store = array("amount" => 250, 
"currency" => "EUR", 
"orderId" => uniqid("MyOrderId"),
"customer" => array(
  "email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];

?>

    

Para obtener más detalles sobre la autenticación de las llamadas al Servicio web REST, consulte: Fase de autenticación.

La respuesta será:

{
    "status": "SUCCESS",
    "_type": "V4/WebService/Response",
    "webService": "Charge/CreatePayment",
    "applicationProvider": "PAYZEN",
    "version": "V4",
    "applicationVersion": "4.1.0",
    "answer": {
        "formToken": "DEMO-TOKEN-TO-BE-REPLACED",
        "_type": "V4/Charge/PaymentForm"
    }
}

2. Mostrar el formulario

Una vez que el formToken esté en su poder, puede visualizar el formulario de pago.

Para ello es necesario:

  • Incluir la biblioteca de JavaScript del formulario de pago (kr-payment-form.min.js) en su página de pago, pasando en argumento su clave de acceso (consulte aquí para saber cómo obtenerla), así como las hojas de estilo asociadas.
  • Incluir un elemento de tipoDIVcon los siguientes argumentos:
    • la clase kr-embedded
    • el atributo kr-form-token en el que ha transferido el formToken recibido en la etapa anterior.

El formulario de pago se mostrará en este DIV.

Es obligatorio que la biblioteca principal se cargue rápidamente, mucho antes que las otras bibliotecas JS utilizadas en su página.

<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" 
   content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />  

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="https://api.lyra.com/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" 
   kr-public-key="69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5" 
   kr-post-url-success="paid.html">
  </script>

  <!-- theme and plugins. should be loaded after the javascript library -->
  <!-- not mandatory but helps to have a nice payment form out of the box -->
  <link rel="stylesheet" 
  href="https://api.lyra.com/static/js/krypton-client/V4.0/ext/classic-reset.css">
 <script 
  src="https://api.lyra.com/static/js/krypton-client/V4.0/ext/classic.js">
 </script> 
</head>
<body>
  <!-- payment form -->
  <div class="kr-embedded" 
   kr-form-token="DEMO-TOKEN-TO-BE-REPLACED">

    <!-- payment form fields -->
    <div class="kr-pan"></div>
    <div class="kr-expiry"></div>
    <div class="kr-security-code"></div>

    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>

    <!-- error zone -->
    <div class="kr-form-error"></div>
  </div>
</body>
</html>
<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" 
   content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" /> 

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
   kr-public-key="<?php echo $client->getPublicKey();?>"
   kr-post-url-success="paid.php">
  </script>

  <!-- theme and plugins. should be loaded after the javascript library -->
  <!-- not mandatory but helps to have a nice payment form out of the box -->
  <link rel="stylesheet" 
   href="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/ext/classic-reset.css">
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/ext/classic.js">
  </script>
</head>
<body style="padding-top:20px">
  <!-- payment form -->
  <div class="kr-embedded"
   kr-form-token="<?php echo $formToken;?>">

    <!-- payment form fields -->
    <div class="kr-pan"></div>
    <div class="kr-expiry"></div>
    <div class="kr-security-code"></div>  

    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>

    <!-- error zone -->
    <div class="kr-form-error"></div>
  </div>  
</body>
</html>

El cliente JavaScript utiliza elementos DIV especiales para insertar los campos del formulario. Estos contenedores se identifican a partir de las siguientes clases:

Class Descripción
kr-pan Número de tarjeta
kr-expiry Fecha de expiración
kr-security-code Código de seguridad (CVV)
kr-form-error Zona de visualización de errores
kr-first-installment-delay Número de meses de diferido que se aplicarán a la primera cuota
kr-identity-document-type Tipo de documento de identidad
kr-identity-document-number Número del documento de identidad
kr-card-holder-name Nombre del titular de la tarjeta
kr-card-holder-mail Dirección e-mail del titular de la tarjeta

Ejemplo de formulario de pago:

Cuando el comprador valida el formulario, la transacción es enviada mediante el formulario directamente a nuestra plataforma de pago para su validación.

  • Si la transacción es validada, se redirige al comprador a la página indicada en el atributo kr-post-url-success de la etiqueta
  • Si la transacción es rechazada aparece un error y el comprador se queda en la página de pago.

3. Verificar el estado de la transacción

Durante el proceso de pago, las 2 siguientes acciones tienen lugar de forma secuencial:

  • Se envía una notificación instantánea (Instant Payment Notification o IPN) que contiene todos los datos de la transacción, haya sido aceptada o rechazada. Debe configurar la URL de notificación de su servidor en el Back Office de la tienda.

    Notificación instantánea (IPN)

  • El navegador también recibe la misma información de transacción al final del proceso de pago.

    Retorno del navegador

Solo necesita procesar uno de estos 2 mensajes (son idénticos). Sirven para validar el carrito de compra e iniciar su proceso de compra.

Ejemplo de información enviada:

kr-hash=c3c0323c748fdb7c2d24bd39ada99663526236828efa795193bebfdea022fe58
kr-hash-algorithm=sha256_hmac
kr-hash-key=sha256_hmac
kr-answer={"orderStatus":"PAID", (...)

La primera etapa consiste en validar la integridad del mensaje, comprobando que la firma (kr-hash) coincida con el conjunto del mensaje.

Una vez validada la integridad del mensaje, puede procesar la transacción (cuyo estado se almacena en la propiedad kr-answer).