Empezar

Quickstart

Crear un cardholder, registrar un medio de pago, emitir una tarjeta single-use y cerrarla. End-to-end con curl en menos de 60 segundos.

Modo de prueba
Todo este flow funciona con una key sk_test_. Las tarjetas emitidas en test mode NO mueven plata real ni se emiten en la red del issuer — sirven para validar el contrato HTTP de tu integración.

0. Configurá las variables

terminal
export ARGENTIVE_KEY="sk_test_..."
export ARGENTIVE_BASE="https://api.argentive.card"

1. Crear un cardholder

Un cardholder es la persona física dueña de las tarjetas. Detrás de este endpoint, Argentive crea el usuario en el card issuer y dispara el KYC contra el documento local (DNI/CUIT en AR, CURP/RFC en MX, RUT en CL).

curl
CH=$(curl -s -X POST "$ARGENTIVE_BASE/api/v1/cardholders" \
  -H "Authorization: Bearer $ARGENTIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ada",
    "lastName": "Lovelace",
    "dateOfBirth": "1990-03-15",
    "phoneNumber": "+5491150000000",
    "email": "ada@argentive.ai",
    "taxId": "20-12345678-9",
    "country": "AR"
  }')

CH_ID=$(echo $CH | jq -r .id)
echo $CH_ID
# ch_01HW3FN4Y8K2RJTM9TWPXKP3VZ

2. Registrar un medio de pago

El medio de pago es la tarjeta real (o CBU/CLABE) sobre la que se hará el hold cuando emitas cards. Argentive devuelve una checkoutUrl hospedada en Mercado Pago o dLocal — redirigís al cardholder ahí.

curl
curl -s -X POST \
  "$ARGENTIVE_BASE/api/v1/cardholders/$CH_ID/payment-method/setup" \
  -H "Authorization: Bearer $ARGENTIVE_KEY"

# {
#   "checkoutUrl": "https://checkout.mercadopago.com/...",
#   "expiresAt": "2026-06-24T14:32:00Z"
# }

Verificar status

curl
curl -s "$ARGENTIVE_BASE/api/v1/cardholders/$CH_ID/payment-method/status" \
  -H "Authorization: Bearer $ARGENTIVE_KEY"

# { "hasPaymentMethod": true, "paymentMethodId": "pm_01HW..." }

3. Emitir una tarjeta single-use

Tu agente le pide una tarjeta de USD 25 para una compra puntual. Argentive hace el hold en el medio de pago + emite una card VIRTUAL en la red del issuer con spend_limit igual al monto. Tres cosas pasan en orden, atómicamente:

  • Verifica que el cardholder tenga payment method activo (422 si no).
  • Pre-autoriza el monto en MP/dLocal (402 si declina, detacha el PM).
  • Emite la card a nivel del issuer con x-idempotency-key.
curl
CARD=$(curl -s -X POST "$ARGENTIVE_BASE/api/v1/cards" \
  -H "Authorization: Bearer $ARGENTIVE_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"amountCents\": 2500,
    \"cardholderId\": \"$CH_ID\",
    \"currency\": \"USD\"
  }")

CARD_ID=$(echo $CARD | jq -r .id)
echo $CARD
# {
#   "id": "card_01HW3FNE2R...",
#   "cardholderId": "ch_01HW3FN4Y8...",
#   "last4": "4242",
#   "expiry": "2030-12",
#   "spendLimitCents": 2500,
#   "balanceCents": 2500,
#   "status": "OPEN",
#   "currency": "USD",
#   "createdAt": "2026-06-24T11:48:23Z"
# }

4. Obtener PAN/CVV (auditado)

Las credenciales sensibles las sirve el issuer a través de un secure data portal tokenizado. Argentive NUNCA las guarda. Este endpoint audita el acceso — cada llamada queda registrada con timestamp + IP + key.

curl
curl -s "$ARGENTIVE_BASE/api/v1/cards/$CARD_ID/details" \
  -H "Authorization: Bearer $ARGENTIVE_KEY"

# {
#   "pan":     "4242 4242 4242 4242",
#   "cvv":     "123",
#   "expiry":  "12/30",
#   "name":    "ADA LOVELACE"
# }
Atención
Cualquier acceso a /details queda auditado y notificable. No expongas este endpoint sin un wrapper que requiera aprobación humana o motivo justificado.

5. Cerrar la tarjeta (libera el hold)

Si la card no se usa (el agente cambió de idea, falló el checkout, expiró el contexto), cerrala. El hold se anula y la plata vuelve al cardholder. Idempotente.

curl
curl -s -X DELETE "$ARGENTIVE_BASE/api/v1/cards/$CARD_ID" \
  -H "Authorization: Bearer $ARGENTIVE_KEY"

# {
#   "id": "card_01HW3FNE2R...",
#   "status": "CLOSED",
#   "closedAt": "2026-06-24T11:53:18Z"
# }

Ejemplo completo

quickstart.sh
#!/usr/bin/env bash
set -euo pipefail

KEY="sk_test_..."
BASE="https://api.argentive.card"

# 1. Cardholder (dispara KYC en el issuer por detrás)
CH=$(curl -s -X POST "$BASE/api/v1/cardholders" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"firstName":"Ada","lastName":"Lovelace","dateOfBirth":"1990-03-15",
       "phoneNumber":"+5491150000000","taxId":"20-12345678-9","country":"AR"}')
CH_ID=$(echo $CH | jq -r .id)

# 2. Payment method
curl -s -X POST "$BASE/api/v1/cardholders/$CH_ID/payment-method/setup" \
  -H "Authorization: Bearer $KEY"

# 3. Card USD 25
CARD=$(curl -s -X POST "$BASE/api/v1/cards" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d "{\"amountCents\":2500,\"cardholderId\":\"$CH_ID\"}")
CARD_ID=$(echo $CARD | jq -r .id)

# 4. Credenciales (auditado)
curl -s "$BASE/api/v1/cards/$CARD_ID/details" -H "Authorization: Bearer $KEY"

# 5. Cerrar (libera hold)
curl -s -X DELETE "$BASE/api/v1/cards/$CARD_ID" -H "Authorization: Bearer $KEY"

Siguiente paso