API Reference

Cards

Una card es una tarjeta Visa virtual single-use emitida en la red de nuestro card issuer, respaldada por un hold en Mercado Pago o dLocal. El ciclo de vida es OPEN → IN_USE → CLOSED.

El objeto Card

ejemplo
{
  "id":               "card_01HW3FNE2RKAW7CMJX...",
  "cardholderId":     "ch_01HW3FN4Y8K2RJTM9TWPXKP3VZ",
  "last4":            "4242",
  "expiry":           "2030-12",
  "brand":            "visa",
  "currency":         "USD",
  "spendLimitCents":  2500,
  "balanceCents":     2500,
  "status":           "OPEN",
  "holdId":           "hold_mp_01HW3FNE2R...",
  "createdAt":        "2026-06-24T11:48:23Z",
  "closedAt":         null
}

Estados

  • OPEN — Card emitida, hold confirmado, sin uso todavía. El balance coincide con el spend limit.
  • IN_USE — Hubo al menos una autorización aprobada. El balance bajó al monto restante (o quedó en 0 si la captura fue exacta).
  • CLOSED — La card está cerrada. Cualquier intento posterior de cobro se rechaza automáticamente.

Crear una card

POST/api/v1/cards

Atómicamente: valida cardholder + payment method, hace hold en MP/dLocal y emite la card en la red del issuer. Si alguno falla, los anteriores se revierten automáticamente.

Body
amountCentsrequired
integer
Spend limit en centavos. Mínimo 100, máximo 5000 por default (ajustable según plan).
cardholderIdrequired
string
ID del cardholder que va a ser dueño de la card.
currency
string
Default según country del cardholder. Soportadas: USD, ARS, MXN, BRL, CLP, COP, PEN, UYU.
metadata
object
Hasta 5 KV pairs arbitrarios. Útil para correlacionar con tu sistema (ej. { "agent_id": "...", "task_id": "..." }).
Headers opcionales
x-idempotency-key
string
UUID/ULID propio de tu lado. Garantiza que el retry no emita dos cards. Ver idempotency.

Request

curl
curl -X POST "$ARGENTIVE_BASE/api/v1/cards" \
  -H "Authorization: Bearer $ARGENTIVE_KEY" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: 01HW3FNE2R-create-card-A" \
  -d '{
    "amountCents":  2500,
    "cardholderId": "ch_01HW3FN4Y8...",
    "currency":     "USD",
    "metadata": {
      "agent_id":  "claude-cli-01",
      "task_id":   "book-flight-2026-07-12"
    }
  }'

Response — 201 Created

response
{
  "id":               "card_01HW3FNE2RKAW7CMJX...",
  "cardholderId":     "ch_01HW3FN4Y8...",
  "last4":            "4242",
  "expiry":           "2030-12",
  "brand":            "visa",
  "currency":         "USD",
  "spendLimitCents":  2500,
  "balanceCents":     2500,
  "status":           "OPEN",
  "createdAt":        "2026-06-24T11:48:23Z"
}

Posibles errores

  • 402 Payment Required — el medio de pago rechazó el hold. Argentive detacha el PM automáticamente. El cardholder tiene que re-onboardearlo.
  • 422 Unprocessable Entity — el cardholder no tiene payment method. La respuesta incluye setupUrl.
  • 403 Forbidden — el cardholder está en kycStatus: rejected o tu cuenta no está habilitada para emitir.

Obtener una card

GET/api/v1/cards/:id

Devuelve la card sin PAN/CVV. No queda auditado.

curl
curl "$ARGENTIVE_BASE/api/v1/cards/card_01HW3FNE2R..." \
  -H "Authorization: Bearer $ARGENTIVE_KEY"

Obtener PAN/CVV (auditado)

GET/api/v1/cards/:id/details
Acceso auditado
Cada llamada queda registrada con timestamp + IP + API key + motivo opcional. Podés configurar notificaciones por email cada vez que se usa este endpoint.

Internamente, este endpoint hace un proxy al secure data portal del issuer. Argentive nunca guarda PAN/CVV en sus servidores. Pasá un header opcional x-reason con un motivo justificable (vuelve en los logs de auditoría).

curl
curl "$ARGENTIVE_BASE/api/v1/cards/card_01HW3FNE2R.../details" \
  -H "Authorization: Bearer $ARGENTIVE_KEY" \
  -H "x-reason: agent fill checkout despegar 2026-07-12"
response
{
  "pan":     "4242 4242 4242 4242",
  "cvv":     "123",
  "expiry":  "12/30",
  "name":    "ADA LOVELACE"
}

Listar cards

GET/api/v1/cards
Query params
status
string
OPEN · IN_USE · CLOSED
Filtrar por estado.
cardholderId
string
Filtrar por cardholder.
currency
string
Filtrar por moneda.
limit
integer
Default 25, max 100.
offset
integer
Default 0.
createdAfter
string (ISO 8601)
Cards creadas después de esta fecha.

Cerrar una card

DELETE/api/v1/cards/:id

Cierra la card en la red del issuer y anula el hold en MP/dLocal si todavía no fue capturado. Si la card ya está en estado CLOSED, el endpoint es idempotente y devuelve 200 con el mismo body.

curl
curl -X DELETE "$ARGENTIVE_BASE/api/v1/cards/card_01HW3FNE2R..." \
  -H "Authorization: Bearer $ARGENTIVE_KEY"
response
{
  "id":         "card_01HW3FNE2R...",
  "status":     "CLOSED",
  "closedAt":   "2026-06-24T11:53:18Z",
  "holdReleased": true
}

Diagrama de ciclo de vida

state machine
            POST /cards
                 │
                 ▼
              ┌──────┐    transaction.authorized      ┌─────────┐
              │ OPEN │ ─────────────────────────────► │ IN_USE  │
              └──────┘                                └─────────┘
                 │                                         │
                 │ DELETE /cards/:id (hold libera)         │ DELETE /cards/:id
                 │                                         │ (no efecto sobre tx ya capturada)
                 ▼                                         ▼
              ┌────────┐                              ┌────────┐
              │ CLOSED │                              │ CLOSED │
              └────────┘                              └────────┘