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.

{
  "name": "Juan Pérez",
  "documentType": "RFC",
  "documentNumber": "ND",
  "accountType": "CB",
  "accountNumber": "646180110400000007",
  "bankId": "0074",
  "totalAmount": 1000,
  "currency": "MXN",
  "paymentDescription": "Pago a proveedor"
}

Referencia de campos:

Campo	Obligatorio	Notas
`name`	✅	Nombre completo del destinatario.
`documentType`	✅	`CURP` o `RFC`.
`documentNumber`	✅	Número de documento del destinatario. En caso de que no sepas el número de documento del destinatario, envía `ND` en el campo `documentNumber`.
`accountType`	✅	`CB`, `TD` o `NC`. Consulta la tabla de tipos de cuenta más abajo.
`accountNumber`	✅	Número de cuenta del destinatario: CLABE de 18 dígitos (`CB`), número de tarjeta de débito (`TD`) o número de celular (`NC`).
`bankId`	✅	Identificador del banco tomado de la lista de bancos.
`totalAmount`	✅	Monto de la dispersión en MXN.
`currency`	✅	`MXN`
`paymentDescription`	Opcional	Descripción breve de la transferencia.
`mail`	Opcional	Correo electrónico del destinatario.

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
`CB`	Cuenta CLABE
`TD`	Tarjeta de Débito
`NC`	Número Celular. El destinatario debe tener su número de celular asociado a su cuenta de depósito.

ℹ️ 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 🇲🇽

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

La solicitud del token (POST /payouts/transfer/v1/tokens) usa tu llave pública:

El init (POST /payouts/transfer/v1/init) usa tu llave privada:

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