Transfer in

Transfer In te permite aceptar pagos con transferencia bancaria en México 🇲🇽. El cliente es redirigido al portal de su banco para autorizar el pago y Kushki te notifica el resultado por webhook o consultando el estado.

Cómo funciona

Obtén la lista de bancos

Llama a GET /transfer/v1/bankList para obtener la lista de bancos disponibles. Muestra al cliente un selector de banco antes de iniciar la transferencia.

[
  { "code": "1001", "name": "BBVA México" },
  { "code": "1002", "name": "Santander México" },
  { "code": "1003", "name": "Banorte" }
]

Solicita un token de Transfer In

Llama a POST /transfer/v1/tokens con el monto, la callback URL y los datos del cliente. Devuelve un token de un solo uso.

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 500,
    "iva": 0,
    "ice": 0,
    "currency": "MXN"
  },
  "callbackUrl": "https://yoursite.com/transfer/return",
  "documentType": "CURP",
  "documentNumber": "GACJ800101HDFRRN09",
  "email": "user@example.com",
  "currency": "MXN",
  "userType": "0"
}

Campo	Obligatorio	Notas
`amount`	✅	Montos en MXN
`callbackUrl`	✅	URL a la que se redirige al cliente después del pago
`documentType`	✅	`CURP`, `RFC`, `PP` o `CC`
`documentNumber`	✅	Número de documento del cliente
`email`	✅	Correo del cliente para las notificaciones de la transacción
`currency`	✅	`MXN`
`userType`	✅	`"0"` = Persona natural, `"1"` = Persona jurídica
`bankId`	Opcional	Preselecciona un banco para el cliente
`paymentDescription`	Opcional	Descripción que aparece en el estado de cuenta bancario del cliente

Inicia la transacción

Llama a POST /transfer/v1/init con el token y el monto. La respuesta trae un redirectUrl: envía ahí al cliente para que complete el pago en el portal de su banco.

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

Respuesta:

{
  "redirectUrl": "https://bank.mx/authorize/...",
  "transactionReference": "6f16659e-b711-4995-a9ae-161aecbd6521",
  "ticketNumber": "319228478889680318"
}

El cliente completa la transferencia

El cliente inicia sesión en el portal de su banco, revisa y confirma la transferencia. Al terminar, el banco lo redirige de vuelta a tu callbackUrl.

Consulta el estado de la transacción

Llama a GET /transfer/v1/status/{token} para obtener el resultado final de la transacción. Usa el token del paso 2 como path parameter.

{
  "status": "APPROVED",
  "ticketNumber": "319228478889680318",
  "documentType": "CURP",
  "documentNumber": "GACJ800101HDFRRN09"
}

Moneda

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

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
`APPROVED`	Transferencia completada y confirmada
`DECLINED`	La transferencia fue rechazada
`INITIALIZED`	Transacción creada: el cliente fue redirigido al banco
`PENDING`	Esperando la confirmación del banco
`FAILED`	La transacción falló
`EXPIRED`	El cliente no completó la transferencia a tiempo

Webhooks

Incluye un array webhooks en tu solicitud de init para recibir notificaciones en tiempo real cuando cambie el estado de la transferencia:

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

Autenticación

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Obtener lista de bancos

Obtén la lista de bancos disponibles para Transfer In.

Solicitar un token de Transfer In

Tokeniza la solicitud de transferencia con el monto, la moneda y la identificación del cliente.

Iniciar transacción

Inicializa la transferencia. Devuelve la URL de redirección al banco y el transaction reference.

Consultar estado

Consulta el resultado final de la transferencia con el token del paso de solicitud del token.

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

Cómo funciona#

Moneda#

Tipos de documento#

Valores de estado de la transacción#

Webhooks#

Autenticación#

Uso de la API#

Endpoints disponibles#