Dispersa a cuentas bancarias
Reparte tu dinero a las cuentas bancarias de tus clientes.
Dispersar pagos con transferencia consiste en entregar dinero a las cuentas de tus clientes. En otras palabras, si ya cuentas con la información bancaria o número celular (si tienes configurado Transfiya) de tus clientes, puedes usar tu cuenta de dispersión de Kushki para depositar directamente en sus cuentas a través de transferencia, usando la lógica que prefieras.
Ideal para:
- Pago a proveedores o vendedores
- Marketplaces
- Aplicaciones de delivery
Detalles de operación por Transfiya
Es una solución para Colombia, que permite realizar transferencias bancarias en tiempo real de empresa a persona (B2P) entre las principales entidades bancarias de Colombia.
A diferencia de los ciclos ACH, si el usuario está registrado en Transfiya, ocurren los siguientes escenarios:
- Transferencia por número de cuenta bancaria: al realizar la transferencia se abona el monto en tiempo real a la cuenta, siempre y cuando, el usuario haya recibido previamente al menos una transferencia por Transfiya en esta cuenta. Si no existe el número de cuenta se rechaza la transacción, de igual forma se rechaza si no ha recibido previamente transferencias, a menos de que se haya hecho un acuerdo comercial donde se estipula que se realice por otro procesador.
- Transferencia por número celular: se verá reflejada de forma inmediata si se tiene una única cuenta asociada al número celular. En el caso de tener más de una, el usuario tiene 12 horas para autorizar la transacción en cualquiera de los bancos disponibles. Una vez autorizado, se transfiere el monto de forma inmediata a su cuenta.
El proceso de dispersión por Transfiya se realiza siguiendo el flujo que aparece a continuación: Comercio > Kushki > Transfiya > Banco > Usuario.
Parámetro | Detalle |
---|---|
Monto mínimo por transacción | 1000 COP |
Monto máximo por transacción | 50,000,000 COP |
Horario de procesamiento con el procesador | 24/7 |
Horario de procesamiento API | 24/7 |
Tiempo en aprobarse una transacción para el destinatario | 12 horas si la transacción se realiza por número celular y de inmediato si es por número de cuenta |
¿Qué pasa si el usuario tiene varias cuentas asociadas a un mismo número de celular?
Si se tiene más de una cuenta asociada a un número celular, todas las transferencias que se hagan a una persona natural por este medio, se tendrán que autorizar desde cualquiera de las entidades bancarias asociadas a su número con Transfiya. Para aceptar cada transferencia se tendrán 12 horas.
Detalles de operación por banco
El proceso de dispersión en Colombia se realiza siguiendo el flujo que aparece a continuación: Comercio > Kushki > Banco > Usuario.
Parámetro | Detalle |
---|---|
Monto mínimo por transacción | 1000 COP |
Monto máximo por transacción | 13,900,000,000 COP (al mismo NIT) |
Monto máximo por beneficiario | 13,900,000,000 COP al día |
Horario de procesamiento con el procesador | Ciclos ACH |
Horario de procesamiento API | 24/7 |
Tiempo en aprobarse una transacción mismo banco | Inmediato |
Tiempo en aprobarse una transacción otros bancos | Hasta 72 horas |
Flujo
El flujo que integrarás es el siguiente:
Aquí aprenderás como integrar las dispersiones de dinero con transferencia.
1. Obtén el listado de bancos asociados
Es importante que te asegures de que todos los bancos a los que realizarás las transferencias se encuentren en el listado de bancos asociados. Te recomendamos realizar la consulta del listado los bancos asociados utilizando nuestro endpoint de listado de bancos.
- Javascript
- Python
- PHP
var request = require('request');var bankList = [];var options = {'method': 'GET','url': 'https://api-uat.kushkipagos.com/payouts/transfer/v1/bankList', // Test environment'headers': {'Public-Merchant-Id': '' // Replace with your Public Key}};request(options, function (error, response) {if (error) throw new Error(error);console.log(response.body);bankList = response.body;// Submit your code to filter the bank you need and send its id in token request});
import requestsurl = "https://api-uat.kushkipagos.com/payouts/transfer/v1/bankList" // Test environmentbankList = []payload = {}headers = {'Public-Merchant-Id': '' // Replace with your Public Key}response = requests.request("GET", url, headers=headers, data = payload)print(response.text.encode('utf8'))bankList = response.text// Submit your code to filter the bank you need and send its id in token request
$client = new http\Client;$request = new http\Client\Request;$request->setRequestUrl('https://api-uat.kushkipagos.com/payouts/transfer/v1/bankList'); // Test environment$request->setRequestMethod('GET');$request->setOptions(array());$request->setHeaders(array('Public-Merchant-Id' => '' // Replace with your Public Key));$client->enqueue($request)->send();$response = $client->getResponse();echo $response->getBody();bankList = $response->getBody();// Submit your code to filter the bank you need and send its id in token request
2. Tokeniza la información.
Ya que has obtenido el código del banco al que está relacionada la cuenta bancaria para realizar la transferencia o tienes Transfiya configurado y cuentas con el número celular del destinatario, deberás realizar la petición del token utilizando nuestro endpoint de tokenización.
Campos obligatorios para obtener el token
Ten en cuenta los campos requeridos en el cuerpo de la petición de token de transfer out, dependiendo de si vas a dispersar a un número de cuenta directamente o a través de un número de celular:
Dispersión a número de cuenta (accountType=CC ,CA ,DE ) | Dispersión a número de celular (accountType=NC ) |
---|---|
- documentType - documentNumber -accountType -accountNumber - bankId - totalAmount - currency | -accountType -accountNumber - totalAmount - currency |
- Javascript
- Python
- PHP
var request = require('request');var options = {'method': 'POST','url': 'https://api-uat.kushkipagos.com/payouts/transfer/v1/tokens', // Test environment'headers': {'Public-Merchant-Id': '', // Replace with your Public Key'Content-Type': 'application/json'},body: JSON.stringify({"name":"John Doe","documentNumber":"123456789","accountNumber":"99999","accountType":"CC","bankId":"000051","totalAmount":49.99,"documentType":"NIT","currency":"COP"})};request(options, function (error, response) {if (error) throw new Error(error);console.log(response.body);// Submit your code to send the token you received to the next request});
import requestsurl = "https://api-uat.kushkipagos.com/payouts/transfer/v1/tokens" // Test environmentpayload = "{\n \"name\": \"John Doe\",\n \"documentNumber\": \"123456789\",\n \"accountNumber\": \"99999\",\n \"accountType\": \"CC\",\n \"bankId\": \"000051\",\n \"totalAmount\": 49.99,\n \"documentType\": \"NIT\",\n \"currency\": \"COP\"\n}"headers = {'Public-Merchant-Id': '', // Replace with your Public Key'Content-Type': 'application/json'}response = requests.request("POST", url, headers=headers, data = payload)print(response.text.encode('utf8'))// Submit your code to send the token you received to the next request
$client = new http\Client;$request = new http\Client\Request;$request->setRequestUrl('https://api-uat.kushkipagos.com/payouts/transfer/v1/tokens'); // Test environment$request->setRequestMethod('POST');$body = new http\Message\Body;$body->append('{"name": "John Doe","documentNumber": "123456789","accountNumber": "99999","accountType": "CC","bankId": "000051","totalAmount": 49.99,"documentType": "NIT","currency": "COP"}');$request->setBody($body);$request->setOptions(array());$request->setHeaders(array('Public-Merchant-Id' => '', // Replace with your Public Key'Content-Type' => 'application/json'));$client->enqueue($request)->send();$response = $client->getResponse();echo $response->getBody();// Submit your code to send the token you received to the next request
3. Inicializa la transacción
En esta etapa, debes recibir el token obtenido e iniciar el proceso de dispersión con Kushki. Deberás realizar una llamada a nuestro endpoint de inicialización para iniciar el pago.
- Javascript
- Python
- PHP
var request = require('request');var options = {'method': 'POST','url': 'https://api-uat.kushkipagos.com/payouts/transfer/v1/init', // Test environment'headers': {'Private-Merchant-Id': '', // Replace with your Private Key'Content-Type': 'application/json'},body: JSON.stringify({"amount":{"subtotalIva":0,"subtotalIva0":49.99,"iva":0},"token":"53de1cb6bbb54011a0a98053d48677e0" // Replace with the token you received})};request(options, function (error, response) {if (error) throw new Error(error);console.log(response.body);});
import requestsurl = "https://api-uat.kushkipagos.com/payouts/transfer/v1/init" // Test environmentpayload = "{\n \"amount\": {\n \"subtotalIva\": 0,\n \"subtotalIva0\": 49.99,\n \"iva\": 0\n },\n \"token\": \"53de1cb6bbb54011a0a98053d48677e0\"\n}" // Replace with the token you receivedheaders = {'Private-Merchant-Id': '', // Replace with your Private Key'Content-Type': 'application/json'}response = requests.request("POST", url, headers=headers, data = payload)print(response.text.encode('utf8'))
$client = new http\Client;$request = new http\Client\Request;$request->setRequestUrl('https://api-uat.kushkipagos.com/payouts/transfer/v1/init'); // Test environment$request->setRequestMethod('POST');$body = new http\Message\Body;$body->append('{"amount": {"subtotalIva": 0,"subtotalIva0": 49.99,"iva": 0},"token": "53de1cb6bbb54011a0a98053d48677e0" // Replace with the token you received}');$request->setBody($body);$request->setOptions(array());$request->setHeaders(array('Private-Merchant-Id' => '', // Replace with your Private Key'Content-Type' => 'application/json'));$client->enqueue($request)->send();$response = $client->getResponse();echo $response->getBody();
La respuesta, entrega un número de ticket y el estado de la transacción.
4. Consulta el estado de la transacción (opcional)
Ahora que la transferencia está próxima a procesarse, puedes conocer el estado de la transacción utilizando webhooks o consultando manualmente utilizando nuestra API
Webhook
El estado de la transacción se notifica automáticamente en el momento en el que el dinero ha sido entregado en la cuenta bancaria.
API
Puedes utilizar nuestro endpoint Get Status, en nuestra API para consultar manualmente el estado de una transacción específica.
5. Prueba tu integración
Existen números de identificación de prueba que puedes utilizar en el ambiente UAT para asegurarte de que tu integración está lista.
- Transacción aprobada:
123456789
- Transacción declinada:
999999990
6. 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.
- Mostrar mensajes en pantalla de acuerdo con las respuestas de Kushki.
- Guardar y registrar todas las respuestas de Kushki (requeridas en caso de necesitar soporte).
- Si no se requiere enviar el comprobante al correo del cliente, no se debe especificar el email en la solicitud del token.
- Si se reciben notificaciones por webhook correctamente, responder a la solicitud con un status 200.
- El botón de pago se deshabilita después del primer clic.
- El logo de Kushki debe ser visible para el cliente. Puedes encontrar nuestro logo en varios formatos aquí.
- Asegurarse que en el cuerpo de la petición se envíen todos los campos requeridos en la referencia API.
Acepta webhooks
Maneja eventos poscobro de la manera correcta.
Dispersión efectivo
Dispersa tu dinero de forma segura a través de efectivo.