API Reference

Payment methods

Un payment_method es el medio de pago real del cardholder (tarjeta o cuenta bancaria) sobre el que Argentive hace el hold cada vez que se crea una card. Soportamos rieles locales en cada país.

Rieles soportados

  • Argentina — Tarjeta de crédito/débito vía Mercado Pago. Próximamente CVU para débito inmediato.
  • México — Tarjeta de crédito/débito vía Mercado Pago + CLABE.
  • Brasil — Cartão de crédito + PIX vía Mercado Pago.
  • Chile, Colombia, Perú, Uruguay — Tarjeta de crédito vía dLocal.

El objeto PaymentMethod

ejemplo
{
  "id":              "pm_01HW3FN6Q9KMJX...",
  "cardholderId":    "ch_01HW3FN4Y8...",
  "type":            "card",
  "provider":        "mercado_pago",
  "last4":           "4242",
  "brand":           "visa",
  "expiry":          "2027-08",
  "country":         "AR",
  "currency":        "ARS",
  "isDefault":       true,
  "status":          "active",
  "createdAt":       "2026-06-24T11:32:18Z"
}

Setup (hosted checkout)

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

Devuelve una URL de checkout hospedada. Redirigís al cardholder, ingresa los datos de su tarjeta o cuenta bancaria, y al volver Argentive tiene un pm_id tokenizado.

Body (opcional)
returnUrl
string
URL a la que se redirige al cardholder al terminar. Default: tu dashboard.
preferred
string
mercado_pago · dlocal
Forzar provider específico.
curl
curl -X POST \
  "$ARGENTIVE_BASE/api/v1/cardholders/ch_01HW3FN4Y8.../payment-method/setup" \
  -H "Authorization: Bearer $ARGENTIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "returnUrl": "https://miapp.com/pm-done" }'
response
{
  "checkoutUrl": "https://checkout.mercadopago.com/v1/init/...",
  "sessionId":   "pmsess_01HW3FN6Q9...",
  "expiresAt":   "2026-06-24T12:32:00Z"
}
Nota
El cardholder tiene 1 hora para completar el checkout. Si expira, generá una nueva sesión llamando a este endpoint de nuevo.

Status

GET/api/v1/cardholders/:id/payment-method/status
response (con PM activo)
{
  "hasPaymentMethod": true,
  "paymentMethodId":  "pm_01HW3FN6Q9...",
  "type":             "card",
  "last4":            "4242",
  "brand":            "visa",
  "expiry":           "2027-08"
}
response (sin PM)
{
  "hasPaymentMethod": false,
  "setupUrl":         "https://checkout.mercadopago.com/v1/init/..."
}

Listar payment methods

GET/api/v1/cardholders/:id/payment-methods

Un cardholder puede tener múltiples payment methods. Solo uno es isDefault: true — ese es el que se usa para holds.

Cambiar el default

PATCH/api/v1/cardholders/:id/payment-methods/:pm_id
curl
curl -X PATCH \
  "$ARGENTIVE_BASE/api/v1/cardholders/ch_01HW3FN4Y8.../payment-methods/pm_01HW3FN6Q9..." \
  -H "Authorization: Bearer $ARGENTIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "isDefault": true }'

Eliminar un payment method

DELETE/api/v1/cardholders/:id/payment-methods/:pm_id

No podés eliminar el único PM activo si el cardholder tiene cards OPEN/IN_USE (esto protege los holds existentes). Cerrá esas cards primero o registrá otro PM y movéle el default.

response — 409 si hay holds activos
{
  "error":   "payment_method_in_use",
  "message": "Payment method pm_01HW... has 2 active holds. Close the cards first.",
  "blockedBy": ["card_01HW3FNE2R...", "card_01HW3FNF9X..."]
}