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

Solicita un token de Transfer In

Llama a POST /transfer/v1/tokens con el monto, el correo y la moneda. Devuelve un token de un solo uso.

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 1000,
    "iva": 0
  },
  "email": "user@example.com",
  "currency": "MXN"
}

Campo	Obligatorio	Notas
`amount`	✅	Montos en MXN
`email`	✅	Correo del cliente para las notificaciones de la transacción
`currency`	✅	`MXN`
`callbackUrl`	Opcional	URL a la que se redirige al cliente después del pago
`userType`	Opcional	`"0"` = Persona natural, `"1"` = Persona jurídica
`documentType`	Opcional	`CURP`, `RFC`, `PP` o `CC`
`documentNumber`	Opcional	Número de documento del cliente
`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 1 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

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#