Transfer Out

Transfer Out te permite enviar fondos directamente a la cuenta bancaria de un destinatario en México 🇲🇽: pagos a proveedores, payouts de marketplace, comisiones o cualquier flujo de dispersión.

Cómo funciona

Obtén la lista de bancos

Llama a GET /payouts/transfer/v1/bankList (o al endpoint v2) para obtener la lista de bancos de destino disponibles. Muestra esta lista para que el operador pueda elegir el banco del destinatario.

Solicita un token de Transfer Out

Llama a POST /payouts/transfer/v1/tokens con los datos bancarios del destinatario y el monto de la dispersión. Devuelve un token.

{
  "documentType": "CURP",
  "documentNumber": "GACJ800101HDFRRN09",
  "accountType": "CB",
  "accountNumber": "123456789012345678",
  "bankId": "001",
  "totalAmount": 500,
  "currency": "MXN",
  "name": "Juan García",
  "mail": "user@example.com",
  "paymentDescription": "Pago proveedor"
}

Referencia de campos:

Campo	Obligatorio	Notas
`documentType`	Opcional	`CURP`, `RFC`, `PP` o `CC`
`documentNumber`	Opcional	Número de documento del destinatario. Para México, ingresa `ND` si no lo conoces.
`accountType`	✅	Consulta la tabla de tipos de cuenta más abajo
`accountNumber`	✅	Número de cuenta bancaria del destinatario
`bankId`	Opcional	Identificador del banco tomado de la lista de bancos
`totalAmount`	✅	Monto de la dispersión en MXN
`currency`	✅	`MXN`
`name`	Opcional	Nombre completo del destinatario. No se permiten caracteres especiales.
`mail`	Opcional	Correo electrónico del destinatario
`paymentDescription`	Opcional	Descripción de la transferencia. No se permiten caracteres especiales.

Inicia la dispersión

Llama a POST /payouts/transfer/v1/init con el token y el monto. Una respuesta exitosa devuelve un ticketNumber y un transactionReference.

{
  "token": "AbCDef123456Z7Ghi8901234jkLMNopQ",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 500,
    "iva": 0,
    "ice": 0,
    "currency": "MXN"
  },
  "webhooks": ["https://yoursite.com/kushki/payout-notify"],
  "fullResponse": "v2"
}

Respuesta:

{
  "ticketNumber": "319228478889680318",
  "transactionReference": "6f16659e-b711-4995-a9ae-161aecbd6521",
  "status": "INITIALIZED"
}

Consulta el estado de la dispersión

Llama a GET /payouts/transfer/v1/transaction/{ticketNumber} para consultar el estado actual. La transferencia puede tardar en procesarse según el banco del destinatario.

{
  "ticketNumber": "319228478889680318",
  "transactionStatus": "APPROVED",
  "totalAmount": 500,
  "currency": "MXN",
  "bankId": "001",
  "documentType": "CURP",
  "documentNumber": "GACJ800101HDFRRN09"
}

Moneda

Moneda	Código	Notas
Peso mexicano	`MXN`	Dos decimales: los montos usan centavos (por ejemplo, `500.00`)

Tipos de cuenta

Valor	Descripción
`CC`	Cuenta Corriente
`CA`	Cuenta de Ahorro
`CB`	Cuenta CLABE
`CM`	Cuenta de Depósito a la Vista
`TD`	Tarjeta de Débito

ℹ️ CB — Cuenta CLABE es el tipo de cuenta principal en México: un código bancario estandarizado de 18 dígitos que se usa en todas las transferencias interbancarias.

Tipos de documento

Valor	Descripción
`CURP`	Clave Única de Registro de Población 🇲🇽
`RFC`	Registro Federal de Contribuyentes 🇲🇽
`PP`	Pasaporte 🇲🇽
`CC`	Documento de identidad 🇲🇽

Valores de estado de la transacción

Estado	Descripción
`INITIALIZED`	Transferencia creada: en proceso con el banco
`APPROVED`	Fondos dispersados correctamente
`DECLINED`	Transferencia rechazada por el banco del destinatario
`FAILED`	La transferencia falló por un error de procesamiento

Consulta tu saldo para dispersiones

Antes de iniciar dispersiones, verifica que tengas saldo suficiente en tu wallet de dispersiones de Kushki:

GET /wallet/v1/merchant/balance

{
  "currentBalance": 5000,
  "currency": "MXN",
  "balanceDate": "2026-06-02T12:00:00Z"
}

Saldo insuficiente

Las operaciones de Transfer Out se financian con el saldo de tu wallet de Kushki. Asegúrate de que tu saldo cubra la dispersión antes de llamar al endpoint del token.

Webhooks

Incluye un array webhooks en la solicitud de init para recibir notificaciones de la dispersión en tiempo real:

{
  "webhooks": ["https://yoursite.com/kushki/payout-notify"]
}

Autenticación

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Obtener lista de bancos

Obtén los bancos de destino disponibles para dispersiones.

Obtener lista de bancos V2

Lista de bancos ampliada con metadata adicional.

Solicitar un token de Transfer Out

Tokeniza los datos bancarios del destinatario y el monto de la dispersión.

Iniciar transacción

Inicia la dispersión por transferencia bancaria. Devuelve un ticketNumber para el seguimiento.

Consultar estado

Consulta el estado actual de una dispersión por ticketNumber.

Saldo del comercio

Consulta el saldo actual de tu wallet de dispersiones en MXN.

¿Tienes una sugerencia sobre esta documentación? Escríbenos.

Cómo funciona#

Moneda#

Tipos de cuenta#

Tipos de documento#

Valores de estado de la transacción#

Consulta tu saldo para dispersiones#

Webhooks#

Autenticación#

Uso de la API#

Endpoints disponibles#

Cómo funciona

Moneda

Tipos de cuenta

Tipos de documento

Valores de estado de la transacción

Consulta tu saldo para dispersiones

Webhooks

Autenticación

Uso de la API

Endpoints disponibles