Instrumentos de Pago

Un instrumento de pago es un método de pago guardado — normalmente una tarjeta — mantenido en archivo para un cliente, de modo que puedas cobrarle nuevamente sin volver a recolectar los datos de la tarjeta. Los instrumentos son la columna vertebral de las compras repetidas, los upsells en un clic y los cargos iniciados por el merchant, como las renovaciones de suscripción.

Tokeflow almacena solo una referencia no sensible y metadatos para cada instrumento (pi_…, marca, últimos 4 dígitos, vencimiento). La tarjeta en sí se cifra en el momento de la recolección y nunca es manejada por tus servidores.

Cómo se crean los instrumentos

Nunca creas un instrumento de pago enviando números de tarjeta en bruto a la API. La tarjeta siempre la recoge el Bridge SDK en el navegador, y el ciphertext que devuelve debe haberse emitido para registro — purpose: 'instrument_enrollment' (independiente) o saveCard: true (dentro de una sesión de checkout). Consulta Tokenización → Opciones. A partir de ahí, un instrumento se crea de una de tres formas:

El endpoint POST /merchants/:merchant_id/payment-instruments de más abajo almacena un ciphertext de registro directamente, sin verificación ni cargo. Un instrumento creado así existe, pero no conserva credencial del proveedor hasta que pase por él un cargo con el titular presente o una verificación de tarjeta exitosa — así que aún no puede cobrarse con credential_on_file.

:::tip Recolección segura de tarjetas Los campos seguros de Tokeflow se ejecutan dentro de iframes aislados y de origen cruzado. Los datos de la tarjeta se cifran en el navegador y nunca llegan a tus servidores, por lo que un instrumento de pago es la única referencia de tarjeta que tu backend llega a ver. :::

Cómo se usan los instrumentos

Una vez que un instrumento existe, referéncialo por su id en cualquier lugar donde se pueda cobrar una tarjeta guardada:

• Cargos en un clic — pasa payment_instrument_id con credential_on_file: true a POST /api/v1/transactions. El cargo usa la credencial del proveedor conservada en el registro — sin datos de tarjeta, sin CVV. Consulta Cobros con credencial almacenada.
• Tarjeta guardada con CVV reescrito — pasa payment_instrument_id junto con un card_ciphertext_id nuevo de la misma tarjeta, cuando quieras un cargo con el titular presente (3DS posible).
• Suscripciones — define o cambia la tarjeta contra la que se cobra una suscripción mediante change-payment-instrument. Las próximas renovaciones se ejecutan como cargos iniciados por el merchant contra el nuevo instrumento.

{
  "payment_method": "credit_card",
  "charge_type": "payment",
  "country": "BR",
  "customer_id": "cust_john_01",
  "payment_instrument_id": "pi_a1b2c3",
  "credential_on_file": true,
  "amount": 15000,
  "currency": "BRL"
}

El objeto del instrumento de pago

Valores de estado

Objeto de ejemplo

{
  "id": "pi_a1b2c3",
  "merchant_id": "mrc_123",
  "customer_id": "cust_john_01",
  "instrument_type": "card",
  "card_brand": "visa",
  "card_type": "credit",
  "last4": "4242",
  "bin": "424242",
  "issuer_country": "BR",
  "exp_month": 12,
  "exp_year": 2028,
  "status": "active",
  "created_at": "2026-01-15T12:30:00.000Z"
}

Endpoints

Todos los endpoints de instrumentos tienen alcance de merchant y se encuentran bajo una ruta de merchant.

• Clave Merchant — el merchant se infiere a partir de la clave; proporciona el id de tu merchant en la ruta.
• Clave Organization — pasa el id del merchant de destino en la ruta; la clave de la org debe tener acceso a ese merchant.

Alcances requeridos: instruments:read para lecturas, instruments:write para mutaciones.

POST/api/v1/merchants/:merchant_id/payment-instruments

Almacena un instrumento tokenizado asociado a un cliente. El registro se deduplica: reenviar un token que ya resuelve a un instrumento almacenado devuelve el instrumento existente con deduplicated: true y un 200, en lugar de crear un duplicado.

Parámetros de ruta

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/payment-instruments \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_2f9a71d4",
    "card_ciphertext_id": "tok_8f3c2a1b9d4e",
    "metadata": {}
  }'

Ejemplo de respuesta — 200

{
  "id": "pi_123",
  "merchant_id": "mrc_123",
  "customer_id": "cust_john_01",
  "card_brand": "visa",
  "card_type": "credit",
  "instrument_type": "card",
  "last4": "4242",
  "bin": "424242",
  "issuer_country": "BR",
  "exp_month": 12,
  "exp_year": 2028,
  "status": "active",
  "deduplicated": false,
  "created_at": "2025-11-20T10:00:00Z"
}

GET/api/v1/merchants/{merchant_id}/payment-instruments

Lista los instrumentos de pago de un merchant. Admite paginación y filtrado.

Autenticación: clave Organization (con alcance al merchant) o clave Merchant.

Parámetros de consulta

curl "https://api.tokeflow.com/api/v1/merchants/mrc_123/payment-instruments?customer_id=cust_john_01&status=active&limit=20" \
  -H "Authorization: Bearer sk_live_mer_xxx"

Respuesta 200 OK

{
  "success": true,
  "data": [
    {
      "id": "pi_a1b2c3",
      "merchant_id": "mrc_123",
      "customer_id": "cust_john_01",
      "instrument_type": "card",
      "card_brand": "visa",
      "card_type": "credit",
      "last4": "4242",
      "bin": "424242",
      "issuer_country": "BR",
      "exp_month": 12,
      "exp_year": 2028,
      "status": "active",
      "created_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c2a",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

PATCH/api/v1/merchants/{merchant_id}/payment-instruments/{payment_instrument_id}

Actualiza el estado de un instrumento. El estado es el único campo mutable.

Autenticación: clave Organization (con alcance al merchant) o clave Merchant.

Cuerpo

curl -X PATCH \
  "https://api.tokeflow.com/api/v1/merchants/mrc_123/payment-instruments/pi_a1b2c3" \
  -H "Authorization: Bearer sk_live_mer_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "status": "revoked" }'

Respuesta 200 OK

{
  "success": true,
  "data": {
    "id": "pi_a1b2c3",
    "merchant_id": "mrc_123",
    "customer_id": "cust_john_01",
    "instrument_type": "card",
    "card_brand": "visa",
    "card_type": "credit",
    "last4": "4242",
    "bin": "424242",
    "issuer_country": "BR",
    "exp_month": 12,
    "exp_year": 2028,
    "status": "revoked",
    "created_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_91ad04",
  "timestamp": "2026-01-15T12:31:00.000Z"
}

DELETE/api/v1/merchants/{merchant_id}/payment-instruments/{payment_instrument_id}

Revoca un instrumento. Después de la revocación, ya no se puede cobrar. Las suscripciones activas que cobran contra él deben moverse primero a otro instrumento.

Autenticación: clave Organization (con alcance al merchant) o clave Merchant.

curl -X DELETE \
  "https://api.tokeflow.com/api/v1/merchants/mrc_123/payment-instruments/pi_a1b2c3" \
  -H "Authorization: Bearer sk_live_mer_xxx"

Respuesta 204 No Content

HTTP/1.1 204 No Content

Errores

Los fallos usan el sobre de error estándar.

{
  "error": {
    "type": "not_found_error",
    "code": "PAYMENT_INSTRUMENT_NOT_FOUND",
    "message": "Payment instrument pi_a1b2c3 was not found for this merchant.",
    "details": {},
    "request_id": "req_8f3c2a",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

Relacionados

• Upsells y downsells en un clic — guarda una tarjeta al cobrar y luego cóbrala con un clic.
• Descripción general del Bridge SDK — recolecta y registra tarjetas del lado del cliente.
• Transacciones — cobra un instrumento guardado.
• Suscripciones — cobra cargos recurrentes contra un instrumento.
• Clientes — el propietario de cada instrumento.
• Autenticación — claves, alcances y resolución de merchant.