Reserva fondos en pagos one click

09 febrero 2023

Separa la autorización y captura en tarjetas suscritas para crear un cobro ahora y capturar los fondos después

Reservar fondos en una tarjeta bajo demanda permite autorizar la disponibilidad de fondos para una tarjeta, pero retrasar la captura de fondos para cuando se complete el servicio. También permite cambiar el monto de la autorización original en caso de que el pedido cambie debido al envío, impuestos o propina.

Cuando un pago es autorizado, el banco garantiza la disponibilidad del monto y lo rentendrá en la tarjeta del cliente por 7 días. Si el pago no es capturado en ese tiempo, será cancelado de manera automática y los fondos se liberarán.

¿Cómo funciona?

Para reservar fondos de una tarjeta bajo demanda deberás:

1. Crear la inscripción de la tarjeta.
2. Iniciar la autorización con Kushki.
3. Kushki intentará realizar la autorización con la entidad emisora de la tarjeta.
4. Si la respuesta es positiva, el comercio podrá elegir entre 2 opciones a ejecutar antes de que el plazo de autorización expire:

• Capturar un monto: En el caso de que se desee hacer efectivo un cobro en la tarjeta del cliente.
• Cancelar la autorización: En el caso de que se desee cancelar la autorización y liberar los fondos de la tarjeta.

El flujo que integrarás será el siguiente:

1. Crea la inscripción de la tarjeta

Sigue las instrucciones dadas en el paso 1 del artículo ”Genera pagos bajo demanda” para aprender cómo realizar la inscripción de una tarjeta.

Si la subscripción se realiza correctamente, recibirás el subscriptionId. Lo siguiente será realizar desde tu backend una petición de autorización para luego hacer una de captura o anulación, dependiendo del caso.

2. Autoriza el cobro

Con el subscriptionId de tu tarjeta recibido en el paso anterior, deberás realizar una llamada a nuestro endpoint de autorización para iniciar la reserva de un monto determinado.

import http.client

conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")

payload = "{\"amount\":{\"ice\":0,\"iva\":0,\"subtotalIva\":0,\"subtotalIva0\":6000,\"currency\":\"MXN\"},\"name\":\"Juan\",\"lastName\":\"Perez\",\"email\":\"juanp@kushkipagos.com\",\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\": \"Diego Osorio\",\"phone\":\"+593988734644\",\"address\":\"Calle 13 Avenida 39 40\",\"city\":\"Lima\",\"region\":\"Lima Metropolitana\",\"country\":\"Perú\",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"Diego Osorio\",\"phone\":\"+593988734644\",\"address\":\"Calle 13 Avenida 39 40\",\"city\": "Lima","region": "Lima Metropolitana ","country": "Perú","zipCode": \"170402\"}},\"fullResponse\":true}

headers = { 'content-type': "application/json" }

conn.request("POST", "/subscriptions/v1/card/1574693127852000/authorize", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/1574693127852000/authorize',
  headers: {'content-type': 'application/json'},
  body: {
    amount: {ice: 0, iva: 0, subtotalIva: 0, subtotalIva0: 6000, currency: 'MXN'},
    name: 'Juan',
    lastName: 'Perez',
    email: 'juanp@kushkipagos.com',
    orderDetails: {siteDomain: 'tuebook.com', 
        shippingDetails: {name: 'Diego Osorio', phone: +593988734644, address: 'Calle 13 Avenida 39 40', city: 'Lima', region: 'Lima Metropolitana', country: 'Perú', zipCode: 170402},
    billingDetails: {name: 'Diego Osorio', phone: +593988734644, address: 'Calle 13 Avenida 39 40', city: 'Lima', region: 'Lima Metropolitana', country: 'Perú', zipCode: 170402}
  },
  fullResponse: true
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"amount":{"ice":0,"iva":0,"subtotalIva":0,"subtotalIva0":6000,"currency":"MXN"},"name":"Juan","lastName":"Perez","email":"juanp@kushkipagos.com","orderDetails": {"siteDomain":"tuebook.com","shippingDetails":{"name":"Diego Osorio","phone":"+593988734644","address":"Calle 13 Avenida 39 40","city": "Lima","region":"Lima Metropolitana","country":"Perú","zipCode":"170402"},"billingDetails":{"name": "Diego Osorio","phone":"+593988734644","address":"Calle 13 Avenida 39 40","city": "Lima","region":"Lima Metropolitana","country":"Perú","zipCode": "170402"}},"fullResponse":true}');

$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card/1574693127852000/authorize');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

Una vez obtenida la respuesta, guarda el ticketNumber ya que será este el identificador para realizar luego la captura, así como también la anulación.

3.1. Genera la captura (Opcional)

Una vez que se requiera recolectar los fondos de la tarjeta, se deberá realizar la llamada a nuestro endpoint de captura.

Captura el monto que definas de acuerdo al autorizado llamando a nuestro endpoint de captura para suscripciones bajo demanda , utilizando el subscriptionId de la tarjeta y el ticketNumber obtenido en la autorización.

import http.client

conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")

payload = "{\"ticketNumber\":\"319228478889680318\",\"amount\":{\"currency\":\"PEN\",\"subtotalIva\":0,\"iva\":0,\"subtotalIva0\":600,\"ice\":0},\"fullResponse\":true}"

headers = { 'content-type': "application/json" }

conn.request("POST", "/subscriptions/v1/card/123442221212/capture", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/123442221212/capture',
  headers: {'content-type': 'application/json'},
  body: {
    ticketNumber: '319228478889680318',
    amount: {currency: 'PEN', subtotalIva: 0, iva: 0, subtotalIva0: 600, ice: 0},
    fullResponse: true
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"ticketNumber":"319228478889680318","amount":{"currency":"PEN","subtotalIva":0,"iva":0,"subtotalIva0":600,"ice":0},"fullResponse":true}');

$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card/123442221212/capture');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

3.2. Anula la autorización (opcional)

Si necesitas anular una autorización puedes hacerlo llamando a nuestro enpoint de anulación de cobros, utilizando el ticketNumber obtenido de la autorización.

import http.client

conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")

payload = "{\"fullResponse\":true,\"amount\":{\"subtotalIva\":10000,\"subtotalIva0\":0,\"ice\":0,\"iva\":0,\"currency\":\"COP\"}}"

headers = { 'content-type': "application/json" }

conn.request("DELETE", "/v1/charges/1528188291221", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

var request = require("request");

var options = {
  method: 'DELETE',
  url: 'https://api-uat.kushkipagos.com/v1/charges/1528188291221',
  headers: {'content-type': 'application/json'},
  body: {
    fullResponse: true,
    amount: {subtotalIva: 10000, subtotalIva0: 0, ice: 0, iva: 0, currency: 'COP'}
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"fullResponse":true,"amount":{"subtotalIva":10000,"subtotalIva0":0,"ice":0,"iva":0,"currency":"COP"}}');

$request->setRequestUrl('https://api-uat.kushkipagos.com/v1/charges/1528188291221');
$request->setRequestMethod('DELETE');
$request->setBody($body);

$request->setHeaders(array(
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

4. Prueba tu integración

Existen tarjetas de prueba que puedes utilizar en el ambiente UAT para asegurarte de que tu integración está lista. Úsalas con cualquier CVV, código postal y fecha de expiración futura.

• Transacción aprobada: 5451951574925480
• Transacción declinada en solicitud de token (front-end): 4574441215190335
• Transacción declinada en autorización: 4349003000047015
• Transacción declinada en captura: 4547004841271012

5. Prepara tu certificación

Toma en consideración las siguientes pautas para aprobar la certificación técnica (requerida para obtener credenciales productivas):

• Los cálculos de los impuestos están correctos.
• No almacenar datos sensibles de tarjeta en tu base de datos (número completo de tarjeta, CVV, etc.).
• Mensajes en pantalla de acuerdo con las respuestas de Kushki.
• Guardar y registrar todas las respuestas de Kushki (requeridas en caso de necesitar soporte).
• El logo de Kushki debe ser visible para el cliente. Puedes encontrar nuestro logo en varios formatos aquí.
• Asegúrate de enviar todos los datos requeridos que se especifican en la Referencia de la API.

Si estás utilizando Kushki.js, considera también lo siguiente:

• El nombre del titular de la tarjeta es requerido.
• El campo de número de tarjeta es requerido.
• El campo de número de tarjeta acepta solo números.
• El campo de número de tarjeta acepta un máximo de 16 dígitos (pueden ser menos).
• El campo de CVV es requerido.
• El campo de CVV acepta solo números.
• El campo de CVV permite un máximo de 4 dígitos y un mínimo de 3.
• El campo de CVV debe ser tipo password.
• La fecha de expiración es requerida.
• La fecha de expiración debe aceptar solamente fechas futuras.
• El botón de pago se deshabilita luego de hacer el primer clic.
• El logo de Kushki debe ser visible para el cliente. Puedes encontrar nuestro logo en varios formatos aquí.
• Asegúrate de enviar los datos de contacto de tu cliente-pagador (contactDetails), junto con los datos de facturación ( orderDetails -> billingDetails) y envío (si tu modelo de negocio lo requiere: orderDetails -> shippingDetails), dentro del request para realizar el cargo. El ejemplo del Body del JSON para el charge, lo podrás encontrar en Referencia de la API.