Reserva fondos en una tarjeta

Separa la autorización y captura para crear un cobro ahora, pero capturar sus fondos luego.

Reservar fondos en una tarjeta permite autorizar la disponibilidad de fondos para una tarjeta, pero retrasar la captura de fondos para cuando se complete el servicio. Por ejemplo, un hotel puede autorizar un pago previo a la llegada del pasajero y luego capturar los fondos cuando se vaya y 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 disponiblidad 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.

Un ejemplo de lo que integrarás es el siguiente:

¿Cómo funciona?

Puedes reservar fondos de una tarjeta de un sólo uso o para una tarjeta inscrita (bajo demanda). Independientemente de la metodología utilizada para capturar la tarjeta, en tu back-end deberás:

  1. Iniciar una autorización con Kushki de acuerdo a tu fuente.
  2. Kushki intentará realizar la autorización con la entidad emisora de la tarjeta.
  3. 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:

Flujo auth y captura

Configura tu back-end

La responsabilidad del back-end es a partir de tu tipo de integración, realizar una petición de autorización para luego hacer una de captura o anulación dependiendo del caso.

Autorización

Para la llamada de autorización existen dos tipos:

Tarjeta de un sólo uso

Cuando el usuario envia el formulario, tu front-end envia un token a un endpoint que hayas especificado. Con este token, deberás realizar una llamada a nuestro endpoint de autorización para iniciar el cobro.

  • Python
  • Javascript
  • PHP
import http.client
conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")
payload = "{\"token\":\"QZPnSP1000000b3MG3062555GhIrcYt5\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":600,\"ice\":0,\"iva\":0,\"currency\":\"USD\"},\"fullResponse\":true}"
headers = { 'content-type': "application/json" }
conn.request("POST", "/card/v1/preAuthorization", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
import request from 'request';
const options = {
method: 'POST',
url: 'https://api-uat.kushkipagos.com/card/v1/preAuthorization',
headers: {'content-type': 'application/json'},
body: {
token: 'QZPnSP1000000b3MG3062555GhIrcYt5', // Reemplázalo por el token obtenido
amount: {subtotalIva: 0, subtotalIva0: 600, ice: 0, iva: 0, currency: 'USD'},
fullResponse: true
},
json: true
};
request(options, (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('{"token":"QZPnSP1000000b3MG3062555GhIrcYt5","amount":{"subtotalIva":0,"subtotalIva0":600,"ice":0,"iva":0,"currency":"USD"},"fullResponse":true}');
$request->setRequestUrl('https://api-uat.kushkipagos.com/card/v1/preAuthorization');
$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.

Tarjeta inscrita (bajo demanda)

Con el subscriptionId de tu tarjeta, deberás realizar una llamada a nuestro endpoint de autorización para iniciar el cobro.

  • Python
  • Javascript
  • PHP
import http.client
conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")
payload = "{\"amount\":{\"ice\":0,\"iva\":0,\"subtotalIva\":0,\"subtotalIva0\":600,\"currency\":\"PEN\"},\"name\":\"Juan\",\"lastName\":\"Perez\",\"email\":\"[email protected]\",\"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: 600, currency: 'PEN'},
name: 'Juan',
lastName: 'Perez',
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":600,"currency":"PEN"},"name":"Juan","lastName":"Perez","email":"[email protected]","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.

Captura

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

Para la llamada de captura existen dos tipos:

Tarjeta de un solo uso

Captura el monto que definas de acuerdo al autorizado llamando a nuestro endpoint de captura, utilizando el ticketNumber obtenido en la autorización

  • Python
  • Javascript
  • PHP
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", "/card/v1/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/card/v1/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/card/v1/capture');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

Tarjeta suscrita (on-demand)

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

  • Python
  • Javascript
  • PHP
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();

Anular autorización (Opcional)

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

  • Python
  • Javascript
  • PHP
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();

Prueba tu integración

Existen tarjetas de prueba que puedes utilizar en modo prueba para asegurarte que tu integracón esta lista. Úsalas con cualquier CVC, código postal y una fecha de expiración en el futuro.

  • 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: 4574441215190335