Dispersa a cuentas bancarias

15 agosto 2024

Reparte tu dinero a las cuentas bancarias de tus clientes o proveedores.

Dispersar pagos con transferencia consiste en entregar dinero a las cuentas de tus clientes. En otras palabras, si dispones de la información bancaria de estos, puedes usar tu cuenta de dispersión de Kushki y por medio de transferencia enviar el dinero a sus cuentas, usando la lógica que prefieras.

Ideal para:

• Pago a proveedores o vendedores
• Marketplaces
• Aplicaciones de delivery

Detalles de operación

El proceso de dispersión en México se hace en la siguiente dirección: Merchant > Kushki > Procesador > Usuario.

** Para enviar pagos mediante número de celular, el destinatario de la transferencia debe haber asociado previamente su cuenta de depósito a su número de celular en su banco, ya sea mediante medios físicos (sucursal bancaria) o electrónicos (aplicación móvil del banco).

Flujo

El flujo que integrarás es el siguiente:

Aquí aprenderás cómo integrar las dispersiones de dinero con transferencia.

1. Obtén el listado de bancos asociados

El primer paso es consultar el listado de bancos disponibles para realizar la transferencia. Para ello debes consumir este endpoint, el cual, te mostrará las instituciones bancarias disponibles para poder realizar la transacción.

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 requests

url = "https://api-uat.kushkipagos.com/payouts/transfer/v1/bankList" // Test environment
bankList = []

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

Como respuesta a esta llamada, recibirás el nombre (name) y el código (code) de los bancos disponibles. Este último debe ser enviado en la solicitud del token de transfer out.

2. Tokeniza la información

Ya que has obtenido el código del banco al que esta relacionada la cuenta bancaria para realizar la transferencia, deberás realizar la petición del token utilizando nuestro endpoint de solicitud de token de transferencia.

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 you Public Key
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "name":"Juan Castro"
      "documentNumber":"ABCED12340013",
      "accountNumber":"646180110400000007",
      "accountType":"CB",
      "bankId":"0090",
      "totalAmount":1000,
      "documentType":"CURP",
      "currency":"MXN",
      "paymentDescription": "A short description of the payment"
    })

};
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 requests

url = "https://api-uat.kushkipagos.com/payouts/transfer/v1/tokens" // Test enviroment 

payload = "{\n  \"name\": \"Juan Castro\",\n \"documentNumber\": \"ABCED12340013\",\n  \"accountNumber\": \"646180110400000007\",\n  \"accountType\": \"CB\",\n  \"bankId\": \"0090\",\n  \"totalAmount\": 1000,\n  \"documentType\": \"CURP\",\n  \"currency\": \"MXN\",\n  \"paymentDescription\": \"A short description of the payment\" \n}"
headers = {
  'Public-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'))

// Submit your code to send the token 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": "Juan Castro"
  "documentNumber": "ABCED12340013",
  "accountNumber": "646180110400000007",
  "accountType": "CB",
  "bankId": "0090",
  "totalAmount": 1000,
  "documentType": "CURP",
  "currency": "MXN"
  "paymentDescription": "A short description of the payment"
}');
$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 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.

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":1000,
        "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 requests

url = "https://api-uat.kushkipagos.com/payouts/transfer/v1/init" // Test environment

payload = "{\n  \"amount\": {\n    \"subtotalIva\": 0,\n    \"subtotalIva0\": 1000,\n    \"iva\": 0\n  },\n  \"token\": \"53de1cb6bbb54011a0a98053d48677e0\"\n}" // Replace with the token you received
headers = {
  '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": 1000,
    "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 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. La respuesta del webhook contendrá las variables processorStatus y processorStatusDescription dentro del objeto metadata con el el estado final de la dispersión:

  "metadata": {
       "processorStatus": "LIQUIDADO",
       "contractID": "AB123",
       "processorStatusDescription": null
   },

Consulta aquí la estructura completa del webhook de dispersión con transferencia.

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

• Número de cuenta: 646180110400000007
• Número de identificación: 123456789
• Tipo de identificación: CURP o RFC
• Tipo de cuenta: CB

Transacción cancelada

• Número de cuenta: 646180206800000003
• Número de identificación: CADM9108029F4
• Tipo de identificación: CURP o RFC
• Tipo de cuenta: CB

Transacción devuelta

• Número de cuenta: 646180206800000003
• Número de identificación: CADM9108029G5
• Tipo de identificación: CURP o RFC
• Tipo de cuenta: CB

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.