> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Billeteras y emisión de tarjetas

> Errores de las billeteras de tus clientes y de las tarjetas emitidas.

Esta página cubre [Billeteras](/client/wallets/balance) y [Emisión de tarjetas](/client/issuing/index). Además de lo que se lista acá, cualquiera de estos endpoints puede devolver los [errores comunes](/client/base/errors/common). 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](#saldo-de-la-billetera) · [Movimientos](#listar-movimientos) · [Detalle de movimiento](#detalle-de-un-movimiento) · [Transferir](#transferir-entre-billeteras) · [Recargar](#recargar-una-billetera) · [Cuentas relacionadas](#listar-cuentas-relacionadas) · [Eliminar cuenta relacionada](#eliminar-una-cuenta-relacionada) · [Extracto](#solicitar-extracto) · [Tarjetas emitidas](#listar-tarjetas-emitidas) · [Emitir](#emitir-una-tarjeta) · [Detalle](#detalle-de-una-tarjeta-emitida) · [Actualizar](#actualizar-una-tarjeta-emitida) · [Cancelar](#cancelar-una-tarjeta-emitida) · [Activar](#activar-una-tarjeta-física) · [Ver datos](#ver-los-datos-de-la-tarjeta) · [Congelar y descongelar](#congelar-y-descongelar) · [Cambiar PIN](#cambiar-el-pin) · [Transacciones](#transacciones-de-una-tarjeta-emitida)

<Note>
  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`.
</Note>

## Billeteras

### Saldo de la billetera

`GET /customers/{customer_id}/balance` · [Referencia](/client/wallets/balance)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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](/client/wallets/transactions)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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](/client/wallets/transaction)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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`<br />`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](/client/wallets/transfer)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10001`<br />`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`<br />`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`<br />`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`<br />`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](/client/wallets/toupwallet)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10001`<br />`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`<br />`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`<br />`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`<br />`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](/client/wallets/related-accounts)

| 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`<br />`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](/client/wallets/delete-related-account)

| 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`<br />`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`<br />`record_not_found` | 404 | Registro no encontrado, Cuenta no existe | La cuenta no existe o se eliminó. | Revisa el `account_id`. | No |
| `10002`<br />`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](#listar-cuentas-relacionadas). | No |

### Solicitar extracto

`POST /customers/{customer_id}/statements/{month}` · [Referencia](/client/wallets/statement)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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`<br />`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](/client/issuing/cards/list)

| 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](/client/issuing/cards/create)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10001`<br />`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`<br />`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`<br />`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`<br />`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`<br />`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](/client/issuing/cards/detail)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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](#listar-tarjetas-emitidas). | No |

### Actualizar una tarjeta emitida

`PUT /issuing/cards/{card_id}` · [Referencia](/client/issuing/cards/update)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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`<br />`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`<br />`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](/client/issuing/cards/delete)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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`<br />`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](/client/issuing/cards/enable-card)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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`<br />`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`<br />`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`<br />`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](/client/issuing/cards/view)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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`<br />`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`<br />`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`<br />`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](/client/issuing/cards/froze) y `PUT /issuing/cards/{card_id}/unfroze` · [Referencia](/client/issuing/cards/unfroze)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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](/client/issuing/cards/update-pin)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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`<br />`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`<br />`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](/client/issuing/cards/transactions)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.