• Francia
Buscar
Categoria
Tags
Argentina
Argentina
Implementación
Formulario incrustado (tarjetas)
API REST
API REST PCI-DSS
Formulario en redirección
Intercambio de ficheros
Pago móvil
Ejemplo de código
Módulos de pago
Back office
Ayuda
FAQ
Contacto

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 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.

/doc/es-AR/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api.cobroinmediato.tech/api-payment/V4/Charge/CreatePayment
{
    "amount":   9900,
    "currency": "ARS",
    "orderId":  "myOrderId-999999",
    "customer": {
        "email": "sample@example.com"
    }
}
{
    "amount":   1500,
    "currency": "PEN",
    "orderId":  "myOrderId-999999",
    "more": "parameters",
    "customer": {
        "email": "sample@example.com"
    }
}
{
    "amount":   20000,
    "currency": "ARS",
    "orderId":  "myOrderId-999999",
    "more": "parameters",
    "customer": {
        "email": "sample@example.com"
    }
}
{
    "amount":   100000,
    "currency": "COP",
    "orderId":  "myOrderId-999999",
    "more": "parameters",
    "customer": {
        "email": "sample@example.com"
    }
}
{
    "amount":   2500,
    "currency": "BRL",
    "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": "COIN",
    "version": "V4",
    "applicationVersion": "4.1.0",
    "answer": {
        "formToken": "DEMO-TOKEN-TO-BE-REPLACED",
        "_type": "V4/Charge/PaymentForm"
    }
}

El formToken generado es Processing...

2. Mostrar el formulario

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

Para que las diferentes etiquetas se muestren correctamente, se debe definir obligatoriamente la codificación de los caracteres de su página.

Para ello, utilice una etiqueta HTML <meta> con el valor "UTF-8". Por ejemplo:

  <head>
    ... 
    <meta charset="UTF-8">
    ...
  </head>

Entonces debes:

  • 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 tipo DIV con 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.

/doc/es-AR/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L45-L85
https://api.cobroinmediato.tech/api-payment/V4/Charge/CreatePayment
<!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://static.cobroinmediato.tech/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" 
   kr-public-key="45789921:testpublickey_qSbs1nvRJEdy74KqANWo6TnGnRsTzwFMd9DYrO9OCdiHD" 
   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://static.cobroinmediato.tech/static/js/krypton-client/V4.0/ext/classic-reset.css">
 <script 
  src="https://static.cobroinmediato.tech/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

Los campos de formulario definidos con

</div>
son opcionales. El cliente de JavaScript agregará automáticamente los campos requeridos por el método de pago o eliminará automáticamente los campos innecesarios.

Ejemplo de formulario de pago:

El formulario está operativo, puede realizar un pago con las tarjetas de prueba de la barra de depuración (esquina inferior izquierda de esta ventana).

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).

© 2023 | Todos los derechos reservados de Cobro Inmediato
2.7.0-doc-1.8