De la cuenta corporativa al seguimiento de los gastos.
La API organiza la operación corporativa en recursos separados, manteniendo cuenta, titulares, tarjetas, compras, facturas y análisis dentro del mismo contrato público.
Cuenta, saldo y límite.
Consulta el estado de la cuenta y la disponibilidad y solicita recargas de límite.
Titulares y tarjetas.
Crea titulares, emite tarjetas virtuales o físicas y aplica reglas de uso.
Compras, facturas y análisis.
Sigue gastos, centros de costo, facturas y agrupaciones analíticas.
Estado de la cuenta corporativa
La activación no se realiza por la API pública. El endpoint GET /corporate/cards/account sigue disponible en cualquier estado para consultar la situación actual del recurso.
Activación aún no solicitada.
El contrato actualizado debe aceptarse en la Cuenta IOPAY.
Solicitud en análisis por el equipo de IOPAY.
Operaciones de la API disponibles.
suspended indica que el recurso no está disponible para la cuenta.Flujo básico
Confirma que el recurso está active.
Define identidad, límite, intervalo y centro de costo.
Elige tipo, límite y restricción de establecimiento cuando corresponda.
Usa compras, facturas, centros de costo y analytics.
Crear titular
{
"name": "NOME HOLDER",
"tax_id": "12345678909",
"amount": 1000,
"interval": "month",
"center_cost": "MeuCenterCost"
}Crear tarjeta
{
"holder_id": "{{holder_id}}",
"name": "Google Ads",
"limit": 100000,
"interval": "month",
"type": "virtual",
"merchant": "GOOGLE"
}merchant define una restricción de establecimiento, no el nombre de la tarjeta. Usa name como identificación interna. Omitir merchant o enviar null no define ninguna restricción por ese campo.Recursos y endpoints
| Área | Operaciones | Ruta principal |
|---|---|---|
| Cuenta | Estado, saldo, límite y recarga. | /corporate/cards/account · /balance · /recharge |
| Titulares | Listar, consultar, crear, actualizar y cancelar. | /corporate/cards/holders |
| Tarjetas por titular | Consultar las tarjetas y compras de un holder. | /holders/{holder_id}/cards · /purchases |
| Tarjetas | Listar, consultar, crear, actualizar y consultar datos sensibles. | /corporate/cards · /{card_id}/secrets |
| Compras | Listado general y por tarjeta/titular. | /corporate/cards/purchases |
| Centros de costo | Gastos agrupados y detalle del centro. | /corporate/cards/cost-centers |
| Facturas | Listar, cambiar el vencimiento y generar el pago. | /corporate/cards/invoices |
| Analytics | Resumen y agrupaciones de gastos. | /corporate/cards/analytics |
Límites, titulares y centros de costo
Límite por regla.
El holder recibe amount e intervalo day, week o month.
Virtual o física.
Asocia la tarjeta al titular y define límite, intervalo y restricción de merchant cuando sea necesario.
Contexto para la operación.
Agrupa gastos y consulta compras, valores y cashback por centro de costo.
Resources y paginación
Las respuestas de éxito identifican el recurso mediante resource. Los listados usan un envoltorio estandarizado con items, limit, total, offset, has_more y query_count.
{
"resource": "list",
"sort": "time-descending",
"items": [],
"limit": 100,
"total": 0,
"offset": 0,
"has_more": false,
"query_count": 0
}limit y offset se admiten en los listados. El límite por defecto es 100 y el máximo es 1000. En consultas compatibles, ?refresh=true actualiza la base IOPAY con los datos más recientes del banco emisor antes de responder.Facturas y análisis de gastos
Vencimiento y pago.
Lista facturas, configura el día de vencimiento entre 1 y 28 y genera los datos de pago de la factura, que pueden incluir brcode y link.
Gastos consolidados.
Consulta el total gastado, el número de compras, el cashback y las agrupaciones por categoría, centro de costo, titular y evolución mensual.
Datos de la tarjeta
El endpoint GET /corporate/cards/{card_id}/secrets devuelve PAN, CVV, caducidad y TTL cuando es necesario para la operación.
Collection pública
La collection reúne los 23 endpoints documentados, ejemplos de éxito y ejemplos de error para flujos relevantes de cuenta, recarga, titulares y operación.