Recibe pagos OneClick con autorización y captura

11 octubre 2023

Conoce los pasos de integración del servicio de autorización y captura con los que puedes obtener el token de pago, realizar la autorización y ejecutar la captura de fondos.

Web

iOS

Android

Esta funcionalidad se encuentra disponible para los siguientes modelos:

☑ Adquirente
☐ Agregador

Recibir pagos OneClick con el esquema de autorización y captura, permite guardar los datos de tarjeta de tu cliente de manera segura, garantizando la disponibilidad del monto en la tarjeta del cliente máximo por 7 días para tarjetas débito y 28 días para tarjetas crédito. Si el pago no es capturado en ese tiempo, los fondos retenidos serán liberados por el banco emisor de nuevo al tarjetahabiente.

Flujo

El flujo que integrarás será el siguiente:

Flujo para pagos one click con autorización y captura para Colombia

1. Crea la inscripción de la tarjeta

Lo primero que debes hacer para generar cobros OneClick con el esquema de autorización y captura, es inscribir la tarjeta de tu cliente. Para realizar la inscripción, sigue las instrucciones dadas en el artículo de Genera pagos one click.

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

2. Autoriza el cargo

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.

Javascript
Python
PHP

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: 50000, currency: 'COP'},
    name: 'John',
    lastName: 'Doe',
    email: 'user@test.com',
    orderDetails: {siteDomain: 'tuebook.com', 
        shippingDetails: {name: 'John Doe', phone: +593988734644, address: 'Calle 13 Avenida 39 40', city: 'Bogotá', region: 'BogotáDC', country: 'Colombia', zipCode: 170402},
    billingDetails: {name: 'John Doe', phone: +593988734644, address: 'Calle 13 Avenida 39 40', city: 'Bogotá', region: 'BogotáDC', country: 'Colombia', zipCode: 170402}
  },
  fullResponse: v2
  },
  json: true
};

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

  console.log(body);
});

import http.client

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

payload = "{\"amount\":{\"ice\":0,\"iva\":0,\"subtotalIva\":0,\"subtotalIva0\":50000,\"currency\":\"COP\"},\"name\":\"John\",\"lastName\":\"Doe\",\"email\":\"userD@test.com\",\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\": \"John Doe\",\"phone\":\"+593988734644\",\"address\":\"Calle 13 Avenida 39 40\",\"city\":\"Bogotá\",\"region\":\"BogotáDC \",\"country\":\"Colombia\",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"John Doe\",\"phone\":\"+593988734644\",\"address\":\"Calle 13 Avenida 39 40\",\"city\": "Bogotá","region": "BogotaDC","country": "Colombia","zipCode": \"170402\"}},\"fullResponse\":v2}

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

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

$body = new http\Message\Body;
$body->append('{"amount":{"ice":0,"iva":0,"subtotalIva":0,"subtotalIva0":50000,"currency":"COP"},"name":"John","lastName":"Doe","email":"user@test.com","orderDetails": {"siteDomain":"tuebook.com","shippingDetails":{"name":"John Doe","phone":"+593988734644","address":"Calle 13 Avenida 39 40","city": "Bogotá","region":"BogotáDC","country":"Colombia","zipCode":"170402"},"billingDetails":{"name": "John Doe","phone":"+593988734644","address":"Calle 13 Avenida 39 40","city": "Bogotá","region":"BogotáDC","country":"Colombia","zipCode": "170402"}},"fullResponse":v2}');

$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();

3. Kushki verifica autorización

Kushki validará la disponibilidad de fondos con la entidad emisora de la tarjeta. Una vez obtenida la respuesta de Kushki, guarda el ticketNumber ya que será este el identificador para realizar luego la captura, así como también la anulación.

4. Reautoriza el cargo (opcional)

Amplía la vigencia o el monto de la autorización antes de realizar la captura de tus fondos, llamando a nuestro endpoint de reautorización.

Javascript
Python
PHP

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api-uat.kushkipagos.com/card/v1/reauthorization',
  headers: {'content-type': 'application/json' , 'Private-Merchant-Id': '13dc47c55c714839800a22824d56126c'
},
  body: {
    ticketNumber: '319228478889680318',
    amount: {currency: 'COP', subtotalIva: 0, iva: 0, subtotalIva0: 50000},
    fullResponse: v2
  },
  json: true
};

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

  console.log(body);
});

import requests

url = "https://api-uat.kushkipagos.com/card/v1/reauthorization"

payload = {
    "ticketNumber": "319228478889680319",
    "amount": {
        "currency": "COP",
        "subtotalIva": 0,
        "iva": 0,
        "subtotalIva0": 50000,
        "ice": 0
    },
    "fullResponse": "v2"
}
headers = {
    "Content-Type": "application/json",
    "Private-Merchant-Id": "13dc47c55c714839800a22824d56126c"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

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

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

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

$request->setHeaders(array(
  'content-type' => 'application/json'
 ' Private-Merchant-Id ' => '13dc47c55c714839800a22824d56126c'
));

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

echo $response->getBody();

5. Captura o libera los fondos

5.1. Realiza la captura (Opcional)

Una vez que se requiera recolectar los fondos de la tarjeta, captura el monto que definas de acuerdo al autorizado llamando a nuestro endpoint de captura para suscripciones OneClick, utilizando el subscriptionId de la tarjeta y el ticketNumber obtenido en la autorización.

Javascript
Python
PHP

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: 'COP', subtotalIva: 0, iva: 0, subtotalIva0: 50000, ice: 0},
    fullResponse: v2
  },
  json: true
};

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

  console.log(body);
});

import http.client

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

payload = "{\"ticketNumber\":\"319228478889680318\",\"amount\":{\"currency\":\"COP\",\"subtotalIva\":0,\"iva\":0,\"subtotalIva0\":50000,\"ice\":0},\"fullResponse\":v2}"

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

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

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

$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();

5.2. Anula la autorización (opcional)

Si necesitas anular una autorización para que se liberen los fondos al tarjetahabiente puedes hacerlo llamando a nuestro enpoint de anulación de cobros, utilizando el ticketNumber obtenido de la autorización.

Javascript
Python
PHP

var request = require("request");

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

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

  console.log(body);
});

import http.client

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

payload = "{\"fullResponse\":v2,\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":50000,\"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"))

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

$body = new http\Message\Body;
$body->append('{"fullResponse":true,"amount":{"subtotalIva":0,"subtotalIva0":50000,"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 el ambiente UAT para asegurarte 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.

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.