API Reference

Cardholders

Un cardholder es la persona física dueña de las tarjetas. Crear un cardholder dispara KYC en el card issuer contra el documento local (DNI/CUIT en AR, CURP/RFC en MX, RUT en CL, etc.).

El objeto Cardholder

ejemplo

{
  "id":           "ch_01HW3FN4Y8K2RJTM9TWPXKP3VZ",
  "firstName":   "Ada",
  "lastName":    "Lovelace",
  "dateOfBirth": "1990-03-15",
  "phoneNumber": "+5491150000000",
  "email":       "ada@argentive.ai",
  "taxId":       "20-12345678-9",
  "country":     "AR",
  "kycStatus":   "approved",
  "createdAt":   "2026-06-24T11:48:00Z",
  "updatedAt":   "2026-06-24T11:48:12Z"
}

Crear un cardholder

POST/api/v1/cardholders

Body

firstNamerequired

string

Nombre legal.

lastNamerequired

string

Apellido legal.

dateOfBirthrequired

string (ISO 8601)

Fecha de nacimiento — yyyy-mm-dd.

phoneNumberrequired

string (E.164)

Teléfono con prefijo internacional.

email

string

Único por cardholder (no por country).

taxIdrequired

string

CUIT en AR (20-...), RFC en MX, RUT en CL, CPF en BR. Validado server-side.

countryrequired

string (ISO 3166-1)

AR · MX · BR · CL · CO · PE · UY

Determina el flow KYC y la moneda default.

identificationType

string

Opcional. DNI / RUT / CURP / CPF.

identificationValue

string

Opcional. Número del documento que matchea el type.

Request

curl

curl -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"
  }'

Response — 201 Created

response

{
  "id":         "ch_01HW3FN4Y8K2RJTM9TWPXKP3VZ",
  "firstName":  "Ada",
  "lastName":   "Lovelace",
  "country":    "AR",
  "kycStatus":  "pending",
  "createdAt":  "2026-06-24T11:48:00Z"
}

Nota

El campo kycStatus arranca en pending. El issuer resuelve KYC de forma async — vas a recibir un webhook cardholder.updated con kycStatus: "approved" o "rejected". Hasta que esté approved, no podés emitir cards.

Obtener un cardholder

GET/api/v1/cardholders/:id

curl

curl "$ARGENTIVE_BASE/api/v1/cardholders/ch_01HW3FN4Y8K2RJTM9TWPXKP3VZ" \
  -H "Authorization: Bearer $ARGENTIVE_KEY"

Listar cardholders

GET/api/v1/cardholders

Query params

limit

integer

Default 25, max 100.

offset

integer

Default 0.

country

string

Filtrar por país (ISO 3166-1).

kycStatus

string

pending · approved · rejected · review

Filtrar por estado de KYC.

curl

curl "$ARGENTIVE_BASE/api/v1/cardholders?country=AR&kycStatus=approved&limit=50" \
  -H "Authorization: Bearer $ARGENTIVE_KEY"

Actualizar un cardholder

PATCH/api/v1/cardholders/:id

Solo se pueden actualizar email, phoneNumber y identificationValue. Para cambios al nombre o taxId hay que crear un nuevo cardholder (es una restricción del emisor regulado).

curl

curl -X PATCH "$ARGENTIVE_BASE/api/v1/cardholders/ch_01HW3FN4Y8..." \
  -H "Authorization: Bearer $ARGENTIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@nuevo.com" }'

Setup de payment method

POST/api/v1/cardholders/:id/payment-method/setup

Devuelve una URL de checkout hospedada (Mercado Pago en AR/MX/BR, dLocal en cross-border) donde el cardholder registra su tarjeta o CBU/CLABE.

response

{
  "checkoutUrl": "https://checkout.mercadopago.com/v1/init/...",
  "expiresAt":   "2026-06-24T12:48:00Z"
}

Status del payment method

GET/api/v1/cardholders/:id/payment-method/status

response

{
  "hasPaymentMethod": true,
  "paymentMethodId":  "pm_01HW3FN6Q9...",
  "type":             "card",
  "last4":            "4242",
  "brand":            "visa",
  "expiry":           "2027-08"
}

Onboarding hosted

POST/api/v1/cardholder_onboarding_sessions

Si querés que el usuario final cree el cardholder él mismo (sin que tu app le pida documentos), creá una sesión de onboarding hosted. Argentive devuelve una URL pública, recolecta los datos del KYC y te devuelve el cardholder creado por webhook.

Body

return_urlrequired

string

URL a la que se redirige el user al terminar.

email

string

Pre-poblar el email.

external_user_id

string

Tu ID interno del user — vuelve en el webhook.

country

string

AR · MX · BR · CL · CO · PE · UY

Pre-seleccionar país.

state

string

Opaque value que vuelve en el webhook (CSRF).

response

{
  "id":         "cos_01HW3FN7XK4MNQ...",
  "url":        "https://onboarding.argentive.card/s/cos_01HW3FN7XK4MNQ",
  "status":     "pending",
  "expiresAt":  "2026-06-25T11:48:00Z"
}

Cuando el cardholder termina el flow, vas a recibir el webhook cardholder_onboarding_session.completed con el cardholderId ya creado.