Transfer in

Transfer In cobra directamente desde la cuenta bancaria de un cliente, sin tarjeta. En Colombia funciona con procesadores, PSE (redirección bancaria) y Bre-B (QR en tiempo real), a través de los mismos endpoints bajo /transfer/v1. Toda integración empieza preguntando qué procesadores tiene el comercio.

Disponibilidad

Los procesadores disponibles y el tipo de integración dependen de la afiliación del comercio y de las políticas de riesgo.

Endpoints

Endpoint	Método y ruta	Credencial	Propósito	Lo usa
Consultar la configuración de Transfer In	`GET /transfer/v1/config`	Pública	Empieza aquí. Lista los procesadores habilitados para el comercio y, cuando aplica, los `supportedFlows` de cada uno	Todos
Consultar lista de bancos	`GET /transfer/v1/bankList`	Pública	Bancos soportados (`code`, `name`)	PSE
Solicitar un token de Transfer In	`POST /transfer/v1/tokens`	Pública	Crea un token de un solo uso	Todos
Iniciar transacción	`POST /transfer/v1/init`	Privada	Inicia la transacción con el token	Todos
Consultar estado	`GET /transfer/v1/status/{token}`	Privada	Estado final de la transacción	Todos
Cancelar transacción	`PATCH /transfer/v1/cancel/{token}`	Privada	Cancela una transacción mientras no tenga estado final	Bre-B

Flujo de integración

Consulta los procesadores

Llama a Consultar la configuración de Transfer In con la credencial Public-Merchant-Id. processors[] lista los procesadores habilitados para el comercio. Es el punto de partida de toda integración directa por API.

Elige el procesador

Una entrada sin supportedFlows es PSE. Una entrada con supportedFlows es un procesador con flujos de pago (Bre-B). Si el comercio tiene varios, usa los supportedFlows de cada entrada para decidir cómo armar cada token.

Solicita el token

El cuerpo depende del procesador; consulta Procesadores de un vistazo más abajo. Los tokens son de un solo uso.

Inicia la transacción

Envía el token y repite el mismo monto. La respuesta depende del procesador: redirectUrl (PSE) o qr (Bre-B).

Confirma el estado final

Por webhook o con Consultar estado.

Kajita y Kushki.js

Estas herramientas no soportan el objeto processor: con ellas no hay consulta de procesadores y la tokenización sigue el proceso de PSE. Bre-B requiere una integración directa por API, donde el token se solicita desde tu backend.

Procesadores de un vistazo

Los procesadores con flujos de pago, como Bre-B, también se conocen como APM (métodos alternativos de pago).

	PSE	Bre-B
Se identifica por	Entrada de `config` sin `supportedFlows`	Entrada de `config` con `supportedFlows`
Solicitud del token	`bankId`, `callbackUrl`, `userType`, `documentType`, `documentNumber`, `email`, además de `amount` y `currency`. Sin objeto `processor`.	`amount`, `currency` y `processor: { name, flowType }`, copiados tal cual de `config`. El resto es opcional; `bankId` no aplica.
Lista de bancos	Requerida	No se usa
Respuesta de `init`	`redirectUrl`	`qr`
Experiencia del cliente	Es redirigido a PSE y luego a su banco	Escanea un QR en su app bancaria
Vigencia	Token: 30 minutos, de un solo uso	QR: 10 minutos
Cancelación	No disponible	Disponible mientras no tenga estado final
Tipos de integración	API directa, Kajita, Kushki.js	Solo API directa
Disponibilidad	General	Beta, en comercios con el procesador habilitado

El token queda ligado al procesador con el que fue generado, y Iniciar transacción lo valida:

Token generado	Procesador del comercio	Resultado
Sin `processor`	PSE	Continúa; la respuesta incluye `redirectUrl`.
Con `processor` de Bre-B	Bre-B	Continúa; la respuesta incluye `qr`.
Con `processor`	Otro procesador	`422 E046`
Sin `processor`	Bre-B	`422 E046`
Con `processor` de Bre-B	Bre-B sin llaves configuradas	`404 E049`

Detalle por procesador

PSE

Bre-B (Beta)

Campos de la solicitud del token

Campo	Requerido	Descripción
`bankId`	Sí	`code` del banco seleccionado de la lista de bancos.
`amount`	Sí	Objeto con `subtotalIva`, `subtotalIva0` e `iva`. Consulta Objeto amount más abajo.
`currency`	Sí	Siempre `COP`.
`callbackUrl`	Sí	URL a la que llega el cliente después de pagar en el banco.
`userType`	Sí	`0` = persona natural · `1` = empresa.
`documentType`	Sí	`CC`, `NIT`, `CE`, `TI` o `PP`.
`documentNumber`	Sí	Número de documento del cliente.
`email`	Sí	Correo electrónico del cliente.

Los tokens expiran a los 30 minutos y son de un solo uso. Si la transacción falla o el token expira, solicita uno nuevo.

`documentType`	Documento
`CC`	Cédula de Ciudadanía
`NIT`	Número de Identificación Tributaria
`CE`	Cédula de Extranjería
`TI`	Tarjeta de Identidad
`PP`	Pasaporte

Campos de la respuesta de init

El redirectUrl es de un solo uso: redirige al cliente apenas lo recibas.

Campo	Descripción
`redirectUrl`	URL de un solo uso para redirigir al cliente a PSE.
`trazabilityCode`	También llamado CUS: código único de referencia del pago en PSE.
`bankId`	Código del banco seleccionado para la transacción.
`bankName`	Nombre del banco seleccionado para la transacción.
`transactionReference`	Referencia única de la transacción.

La respuesta del estado también incluye el trazabilityCode (CUS), que puedes usar para conciliar la transacción con los registros de PSE.

Estados

Confirma el resultado final con Consultar estado, usando el token original como parámetro de ruta. El webhook y los estados son los mismos para todos los procesadores.

Estado	Significado
`initializedTransaction`	La transacción se creó pero no se completó.
`approvedTransaction`	La transferencia fue autorizada.
`declinedTransaction`	La transferencia fue rechazada.

Objeto amount

El objeto amount es obligatorio en la solicitud del token. Usa la siguiente estructura según si la transacción tiene impuestos o no:

Con IVA

Sin impuestos (IVA 0)

Con impuestos adicionales

{
  "amount": {
    "subtotalIva": 100000,
    "subtotalIva0": 0,
    "iva": 10000
  }
}

Pon en subtotalIva la base gravable y en iva el valor del impuesto. Pon subtotalIva0 en 0. Todos los montos en COP.

Notificaciones por webhook

Puedes recibir notificaciones de la transacción en tiempo real incluyendo el objeto webhooks en tu solicitud de Init Transaction. Esto es independiente de los webhooks configurados en la Kushki Console: los dos canales se disparan al mismo tiempo.

{
  "webhooks": [
    {
      "events": ["approvedTransaction", "declinedTransaction"],
      "headers": [
        { "label": "Authorization", "value": "Bearer your-token" }
      ],
      "urls": [
        "https://merchant.example.com/webhooks/transfer-in"
      ]
    }
  ]
}

Errores

Procesador	Endpoint	HTTP	Código	Cuándo ocurre	Qué hacer
Todos	`GET /transfer/v1/config`	`500`	`E002`	Error al consultar la configuración del comercio («Ha ocurrido un error inesperado.»).	Reintenta; contacta a soporte si persiste.
Bre-B	`POST /transfer/v1/tokens`	`400`	—	El cuerpo no cumple el contrato: falta un campo requerido, valor fuera del enumerado (`processor.name`, `processor.flowType`) o propiedad adicional dentro de `processor`.	Corrige el cuerpo según `config`.
Todos	`POST /transfer/v1/init`	`422`	`E046`	El token no es compatible con el procesador resuelto.	Regenera el token para el procesador correcto.
Bre-B	`POST /transfer/v1/init`	`404`	`E049`	El comercio no tiene un procesador Bre-B configurado (faltan las llaves).	Verifica la configuración del procesador con Kushki.
Bre-B	`PATCH /transfer/v1/cancel/{token}`	`400`	`T023`	La transacción ya alcanzó un estado final.	Ninguna: no se puede cancelar.
Todos	Cualquiera	`401`	—	Credencial ausente o inválida.	Revisa `Public-Merchant-Id` o `Private-Merchant-Id`, según el endpoint.

Autenticación y entornos

Las credenciales se envían en un header; cada endpoint usa una de ellas (consulta la columna Credencial de arriba):

Header	Credencial	Uso
`Public-Merchant-Id`	Pública	Configuración, lista de bancos y tokenización.
`Private-Merchant-Id`	Privada	Init, estado y cancelación. Nunca la expongas en código de frontend.

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints#

Flujo de integración#

Procesadores de un vistazo#

Detalle por procesador#

Estados#

Objeto amount#

Notificaciones por webhook#

Errores#

Autenticación y entornos#

Endpoints

Flujo de integración

Procesadores de un vistazo

Detalle por procesador

Estados

Objeto amount

Notificaciones por webhook

Errores

Autenticación y entornos