Billeteras y emisión de tarjetas

Esta página cubre Billeteras y Emisión de tarjetas. Además de lo que se lista acá, cualquiera de estos endpoints puede devolver los errores comunes. Los que tienen un ID en la ruta también responden 404 record_not_found si el ID no es un UUID, y 404 environment_key_mismatch si el recurso es del otro ambiente. Endpoints: Saldo · Movimientos · Detalle de movimiento · Transferir · Recargar · Cuentas relacionadas · Eliminar cuenta relacionada · Extracto · Tarjetas emitidas · Emitir · Detalle · Actualizar · Cancelar · Activar · Ver datos · Congelar y descongelar · Cambiar PIN · Transacciones

Los errores de saldo (10500 y 10501) responden con HTTP 401, no con 402 ni 422. No los trates como un problema de autenticación: decide por code_name.

Billeteras

Saldo de la billetera

GET /customers/{customer_id}/balance · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, Cliente no existe	El cliente no existe, se eliminó o es de otra empresa.	Revisa el `customer_id`.	No

Listar movimientos

GET /customers/{customer_id}/transactions · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, Cliente no existe	El cliente no existe, se eliminó o es de otra empresa.	Revisa el `customer_id`.	No

Detalle de un movimiento

GET /customers/{customer_id}/transactions/{transaction_id} · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, Cliente no existe	El cliente no existe, se eliminó o es de otra empresa.	Revisa el `customer_id`.	No
`10002` `record_not_found`	404	Registro no encontrado, Transaction no existe	El movimiento no existe o no es de la billetera de ese cliente.	Revisa el `transaction_id` y que sea del cliente de la URL.	No

Transferir entre billeteras

POST /customers/transfer · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10001` `validation_error`	422	El origin seleccionado es inválido.	`origin` o `destination` falta, no es un UUID o no existe como billetera, o `amount` está fuera de 1 a 100.000.000.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir
`10001` `validation_error`	422	No se permite transferir a la misma billetera.	`origin` y `destination` son la misma billetera.	Usa otra billetera de destino.	Sí, tras corregir
`10001` `validation_error`	422	La billetera destino debe estar en la misma moneda que la de origen.	Las billeteras están en monedas distintas.	Transfiere entre billeteras de la misma moneda.	Sí, tras corregir
`10500` `balance_is_empty`	401	Tu saldo está vacío, necesitas depositar fondos para continuar con la operación.	Este endpoint responde lo mismo para varias causas: saldo en cero o insuficiente, una billetera de origen que no es tuya, una billetera del otro ambiente, o un error interno.	Revisa que `origin` sea una billetera tuya, que las dos sean del mismo ambiente y que haya saldo. Luego reintenta con el mismo `external_id`.	Sí, tras revisar

Recargar una billetera

POST /customers/{customer_id}/transactions · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10001` `validation_error`	422	El campo concept es obligatorio.	Falta `concept` o `amount`, `amount` no es un número o está fuera de 1 a 100.000.000, o `external_id` tiene más de 255 caracteres.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir
`10002` `record_not_found`	404	Registro no encontrado, Cliente no existe	El cliente no existe, se eliminó o es de otra empresa.	Revisa el `customer_id`.	No
`10500` `balance_is_empty`	401	Tu saldo está vacío, necesitas depositar fondos para continuar con la operación.	El saldo de tu empresa en este ambiente está en cero.	Recarga el saldo de tu empresa.	Sí, tras recargar
`10501` `insufficient_funds`	401	No tienes fondos suficientes para hacer está operación.	El monto supera el saldo disponible de tu empresa en este ambiente.	Recarga el saldo o envía un monto menor.	Sí, tras recargar
Sin código	500	Server Error	La billetera estaba ocupada con otra operación y no se pudo completar la recarga.	Reintenta con el mismo `external_id`: si la recarga ya quedó, recibes la existente.	Sí, con espera

external_id es único entre recargas y transferencias: si reusas uno de una transferencia en una recarga, recibes el movimiento existente con 200.

Listar cuentas relacionadas

GET /customers/{customer_id}/accounts/related · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
Sin código	403	Company does not have this feature.	Tu empresa no tiene activa la emisión de tarjetas.	Pídele a soporte que la active.	No
`10002` `record_not_found`	404	Registro no encontrado, Cliente no existe	El cliente no existe, se eliminó o es de otra empresa.	Revisa el `customer_id`.	No

Eliminar una cuenta relacionada

DELETE /customers/{customer_id}/accounts/related/{account_id} · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
Sin código	403	Company does not have this feature.	Tu empresa no tiene activa la emisión de tarjetas.	Pídele a soporte que la active.	No
`10002` `record_not_found`	404	Registro no encontrado, Cliente no existe	El cliente no existe, se eliminó o es de otra empresa.	Revisa el `customer_id`.	No
`10002` `record_not_found`	404	Registro no encontrado, Cuenta no existe	La cuenta no existe o se eliminó.	Revisa el `account_id`.	No
`10002` `record_not_found`	404	Registro no encontrado	La cuenta no está relacionada con ese cliente (también en un segundo `DELETE`).	Usa un `id` de listar cuentas relacionadas.	No

Solicitar extracto

POST /customers/{customer_id}/statements/{month} · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, Cliente no existe	El cliente no existe, se eliminó o es de otra empresa.	Revisa el `customer_id`.	No
`10002` `record_not_found`	404	Registro no encontrado	`month` no tiene la forma `AAAA-MM` (por ejemplo `2026-2`).	Envía el mes como `AAAA-MM`, por ejemplo `2026-02`.	Sí, tras corregir
Sin código	422	Formato de mes inválido: ‘2026-13’. Use el formato YYYY-MM (ejemplo: 2026-02).	`month` tiene la forma `AAAA-MM` pero no es un mes real.	Envía un mes entre `01` y `12`.	Sí, tras corregir
Sin código	422	No es posible solicitar extractos del mes en curso o meses futuros.	El mes todavía no ha cerrado. Se habilita el día 1 del mes siguiente a las 00:00, hora de Colombia.	Pide un mes ya cerrado.	Sí, cuando cierre el mes
Sin código	404	No tienes una wallet asociada.	El cliente nunca ha tenido billetera.	No hay movimientos que reportar.	No

Emisión de tarjetas

Todas las rutas de /issuing responden 403 con {"message": "Company does not have this feature."} si tu empresa no tiene activa la emisión de tarjetas.

Listar tarjetas emitidas

GET /issuing/cards · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
Sin código	400	Requested filter(s) `…` are not allowed. Allowed filter(s) are `status, type, last_4, nickname`.	Enviaste un filtro que no existe.	Usa solo los filtros de la lista.	Sí, tras corregir
Sin código	400	Requested sort(s) `…` is not allowed. Allowed sort(s) are `created_at`.	Enviaste un orden que no existe.	Ordena por `created_at` o `-created_at`.	Sí, tras corregir

Emitir una tarjeta

POST /issuing/cards · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10001` `validation_error`	422	Cliente no encontrado.	`customer_id` no existe, no es de tu empresa («Cliente no pertenece a la empresa.») o es de prueba y usas la llave de producción.	Usa un cliente tuyo del mismo ambiente.	Sí, tras corregir
`10001` `validation_error`	422	Billetera no encontrada.	`wallet_id` no existe o no es de ese cliente («Billetera no pertenece al usuario.»).	Usa una billetera del cliente.	Sí, tras corregir
`10001` `validation_error`	422	La empresa alcanzó el tope de N tarjetas vigentes. Cancela alguna o pide a OnePay que amplíe el tope.	Tu empresa llegó al máximo de tarjetas vigentes (creadas, activas o congeladas). Llega en `errors.type`.	Cancela una tarjeta vigente o pídele a soporte que amplíe el tope.	Sí, tras liberar cupo
`10001` `validation_error`	422	El campo nickname debe contener al menos 5 caracteres.	Algún campo no cumple su formato: `nickname` de 5 a 50 caracteres, `type` `virtual` o `physical`, o la dirección incompleta.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir
`18005` `active_cards_limit_reached`	422	La empresa alcanzó el tope de N tarjetas vigentes. Cancela alguna o pide a OnePay que amplíe el tope.	Otra emisión simultánea llenó el tope justo antes que esta.	Cancela una tarjeta vigente o pídele a soporte que amplíe el tope.	Sí, tras liberar cupo

La emisión con el emisor ocurre en segundo plano: la tarjeta nace en created y un fallo del emisor no vuelve como error en esta respuesta.

Detalle de una tarjeta emitida

GET /issuing/cards/{card_id} · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, IssuingCard no existe	La tarjeta no existe, se eliminó o es de otra empresa.	Revisa el `card_id` con listar tarjetas emitidas.	No

Actualizar una tarjeta emitida

PUT /issuing/cards/{card_id} · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, IssuingCard no existe	La tarjeta no existe, se eliminó o es de otra empresa.	Revisa el `card_id`.	No
`10001` `validation_error`	422	El campo nickname debe contener al menos 5 caracteres.	`nickname` está fuera de 5 a 50 caracteres o `status` no es un estado válido.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir
Sin código	409	Invalid status transition.	Enviaste `status` `created` o `expired`, que no se pueden asignar.	Usa `active`, `frozen` o `cancelled`.	Sí, tras corregir
`18000` `card_has_benn_cancelled`	409	La tarjeta ha sido cancelada, no puede continuar con la operación.	Pediste cancelar una tarjeta que ya estaba cancelada.	Nada: la tarjeta ya está cancelada.	No
Sin código	500	Server Error	El emisor de la tarjeta no respondió o rechazó el cambio. El cambio de estado no se aplica.	Reintenta con espera. Si persiste, escribe a soporte con el `x-request-id`.	Sí, con espera

Cancelar una tarjeta emitida

DELETE /issuing/cards/{card_id} · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, IssuingCard no existe	La tarjeta no existe, se eliminó o es de otra empresa.	Revisa el `card_id`.	No
`18000` `card_has_benn_cancelled`	409	La tarjeta ha sido cancelada, no puede continuar con la operación.	La tarjeta ya estaba cancelada (por ejemplo, un segundo `DELETE`).	Nada: la tarjeta ya está cancelada.	No
Sin código	500	Server Error	El emisor de la tarjeta no respondió o rechazó la cancelación.	Reintenta con espera. Si persiste, escribe a soporte con el `x-request-id`.	Sí, con espera

Activar una tarjeta física

GET /issuing/cards/{card_id}/enable · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, IssuingCard no existe	La tarjeta no existe, se eliminó o es de otra empresa.	Revisa el `card_id`.	No
`10004` `read_only_key_not_supported`	403	La clave de solo lectura no es soportada para esta petición	Usaste una llave de solo lectura; este endpoint genera un enlace de activación.	Usa una llave privada (`sk_`).	No
`18002` `card_is_not_physical`	409	La tarjeta no es física, por lo que no puede activarla.	La tarjeta es virtual.	Solo las tarjetas físicas se activan con este endpoint.	No
`18001` `card_is_already_active`	409	La tarjeta ya está activa, no puede activarla nuevamente.	La tarjeta física ya está activa.	Nada: ya está activa.	No

Si la tarjeta física está congelada, cancelada o vencida, la respuesta es 200 con url: null.

Ver los datos de la tarjeta

GET /issuing/cards/{card_id}/view · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, IssuingCard no existe	La tarjeta no existe, se eliminó o es de otra empresa.	Revisa el `card_id`.	No
`10004` `read_only_key_not_supported`	403	La clave de solo lectura no es soportada para esta petición	Usaste una llave de solo lectura; este endpoint expone los datos de la tarjeta.	Usa una llave privada (`sk_`).	No
`18003` `card_is_not_active`	409	La tarjeta no está activa, debe activarla antes de continuar.	La tarjeta no está activa o el emisor todavía no termina de emitirla.	Activa la tarjeta o espera a que termine la emisión.	Sí, cuando esté activa
`18004` `card_is_cant_visualized`	409	La tarjeta no puede ser visualizada ahora mismo, por favor intente más tarde.	El emisor no entregó la vista de la tarjeta.	Reintenta más tarde.	Sí, con espera

Congelar y descongelar

PUT /issuing/cards/{card_id}/froze · Referencia y PUT /issuing/cards/{card_id}/unfroze · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, IssuingCard no existe	La tarjeta no existe, se eliminó o es de otra empresa.	Revisa el `card_id`.	No
Sin código	500	Server Error	El emisor de la tarjeta no respondió o rechazó el cambio.	Reintenta con espera. Si persiste, escribe a soporte con el `x-request-id`.	Sí, con espera

Cambiar el PIN

PUT /issuing/cards/{card_id}/pin · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, IssuingCard no existe	La tarjeta no existe, se eliminó o es de otra empresa.	Revisa el `card_id`.	No
`10001` `validation_error`	422	El campo pin debe tener 4 dígitos.	Falta `pin` o no son exactamente 4 dígitos.	Envía un PIN de 4 dígitos como texto.	Sí, tras corregir
`18002` `card_is_not_physical`	409	La tarjeta no es física, por lo que no puede activarla.	La tarjeta es virtual: solo las físicas tienen PIN.	No cambies el PIN de tarjetas virtuales.	No
Sin código	500	Server Error	El emisor no respondió o rechazó el cambio (también si la tarjeta todavía no está emitida o está cancelada).	Revisa el estado de la tarjeta y reintenta con espera.	Sí, con espera

Transacciones de una tarjeta emitida

GET /issuing/cards/{card_id}/transactions · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, IssuingCard no existe	La tarjeta no existe, se eliminó o es de otra empresa.	Revisa el `card_id`.	No
Sin código	400	Requested filter(s) `…` are not allowed. Allowed filter(s) are `status, currency`.	Enviaste un filtro que no existe.	Usa solo los filtros de la lista.	Sí, tras corregir

API

Empresas

Métodos de pago

Recaudo

Productos

Facturación

Balances

Webhooks

Fintech as a service

Billeteras

Saldo de la billetera

Listar movimientos

Detalle de un movimiento

Transferir entre billeteras

Recargar una billetera

Listar cuentas relacionadas

Eliminar una cuenta relacionada

Solicitar extracto

Emisión de tarjetas

Listar tarjetas emitidas

Emitir una tarjeta

Detalle de una tarjeta emitida

Actualizar una tarjeta emitida

Cancelar una tarjeta emitida

Activar una tarjeta física

Ver los datos de la tarjeta

Congelar y descongelar

Cambiar el PIN

Transacciones de una tarjeta emitida

​Billeteras

​Saldo de la billetera

​Listar movimientos

​Detalle de un movimiento

​Transferir entre billeteras

​Recargar una billetera

​Listar cuentas relacionadas

​Eliminar una cuenta relacionada

​Solicitar extracto

​Emisión de tarjetas

​Listar tarjetas emitidas

​Emitir una tarjeta

​Detalle de una tarjeta emitida

​Actualizar una tarjeta emitida

​Cancelar una tarjeta emitida

​Activar una tarjeta física

​Ver los datos de la tarjeta

​Congelar y descongelar

​Cambiar el PIN

​Transacciones de una tarjeta emitida

Billeteras

Saldo de la billetera

Listar movimientos

Detalle de un movimiento

Transferir entre billeteras

Recargar una billetera

Listar cuentas relacionadas

Eliminar una cuenta relacionada

Solicitar extracto

Emisión de tarjetas

Listar tarjetas emitidas

Emitir una tarjeta

Detalle de una tarjeta emitida

Actualizar una tarjeta emitida

Cancelar una tarjeta emitida

Activar una tarjeta física

Ver los datos de la tarjeta

Congelar y descongelar

Cambiar el PIN

Transacciones de una tarjeta emitida