Conectores

Un conector es un conjunto de credenciales configurado para un proveedor de servicios de pago (PSP). Conectar el mismo proveedor dos veces — por ejemplo, un conjunto de credenciales en modo de prueba y otro en modo producción, o una cuenta por país — produce dos conectores independientes. Todo lo que ocurre después de la configuración habla en términos de conectores, no de proveedores: los perfiles de enrutamiento referencian conectores, y cada intento en la cronología de una transacción registra el connector_id por el que pasó.

Tokeflow orquesta los cobros a través de tus conectores; no procesa ni liquida fondos. El conector es donde le entregas a Tokeflow las credenciales del proveedor que necesita para enviar cobros en tu nombre — y donde configuras los webhooks del proveedor para que los eventos asíncronos (confirmaciones de PIX, contracargos, actualizaciones de reembolso) vuelvan a llegar.

Cómo se crea un conector

Usa GET /payment-providers para descubrir qué proveedores están disponibles para conectar y qué métodos de autenticación admite cada uno, crea el conector y luego apunta tu enrutamiento hacia él.

El objeto conector

Configuración del conector

config contiene anulaciones no sensibles por conector:

Al actualizar, cada clave se fusiona de forma independiente: envía un array vacío u omite card_brands para borrar la anulación de marcas, y envía installments_enabled: null para volver al estado sin definir.

Conectores activos e inactivos

Un conector inactivo (is_active: false) es omitido por la evaluación de enrutamiento y es rechazado como conector predeterminado de un perfil de enrutamiento por PATCH /routing/profiles/:id/default-connector. Desactivar es la forma segura de sacar un conjunto de credenciales de la rotación sin eliminarlo.

Cuando Tokeflow retira de servicio un proveedor de pago, sus conectores todavía pueden renombrarse, rotar sus credenciales y desactivarse — pero un conector desactivado no puede volver a activarse (400) mientras el proveedor esté inactivo.

Credenciales rechazadas

Si un proveedor empieza a rechazar las credenciales de API de un conector — una clave revocada, rotada o restringida del lado del proveedor —, Tokeflow confirma el rechazo con el proveedor antes de actuar. Una vez confirmado, las renovaciones de suscripciones enrutadas a ese conector quedan en una retención de facturación en lugar de rechazarse y pasar a dunning. Guarda credenciales nuevas con PATCH y la retención se libera; cambiar solo el webhook_secret no la libera.

Endpoints

Todos los endpoints de conector están delimitados bajo la ruta del merchant. Con una clave de Organization, merchant_id selecciona el merchant de destino; con una clave de Merchant, debe ser el propio merchant de la clave.

POST/api/v1/merchants/:merchant_id/connectors

Registra un conjunto de credenciales de PSP para el merchant. Las credenciales se validan con el proveedor y se almacenan cifradas. Usa GET /payment-providers para listar los proveedores disponibles para conectar y los métodos de autenticación que admite cada uno.

Campos de la solicitud

El objeto credentials

La forma de credentials depende del proveedor conectado. Algunos proveedores requieren una única clave de API; otros requieren un token de acceso más un país, o un par OAuth client_id/client_secret. Envía exactamente los campos que tu proveedor requiere — las claves desconocidas se rechazan, y Tokeflow cifra los valores en reposo y nunca los devuelve por completo. El entorno de la clave debe coincidir con is_test_mode: una clave de producción en un conector de prueba (o al revés) se rechaza antes de almacenar nada. Los slugs de proveedor y sus requisitos exactos de credenciales aparecen listados para tus proveedores habilitados en el Dashboard de Tokeflow.

Credenciales por proveedor

Los campos exactos de credentials, el formato del webhook_secret y cualquier dato extra del pagador que un proveedor exija se muestran para tus proveedores habilitados en el Dashboard de Tokeflow, y el equipo de Tokeflow puede confirmarlos para un proveedor que estés a punto de habilitar. Tres patrones cubren el catálogo:

Sea cual sea el patrón, registra el webhook_url del conector en el panel del propio proveedor y envía payer_ip y un cliente completo en los cargos con tarjeta de los proveedores que los exigen — consulta Proveedores compatibles.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_123/connectors \
  -H "Authorization: Bearer sk_live_org_…" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_slug": "provider_a",
    "name": "Provider A BRL",
    "country_code": "BR",
    "is_test_mode": false,
    "auth_method": "api_key",
    "credentials": { "api_key": "sk_live_provider_key" },
    "webhook_secret": "whsec_9c41f2ab…",
    "config": { "card_brands": ["visa", "mastercard"] }
  }'

Ejemplo de respuesta — 201 Created

{
  "id": "conn_9f2b71",
  "merchant_id": "mrc_123",
  "provider_slug": "provider_a",
  "payment_provider_id": "pp_1a2b3c",
  "name": "Provider A BRL",
  "country_code": "BR",
  "auth_method": "api_key",
  "is_test_mode": false,
  "is_active": true,
  "created_at": "2026-01-15T12:30:00Z",
  "webhook_url": "https://api.tokeflow.com/webhooks/connectors/conn_9f2b71?token=whsec_…",
  "has_webhook_secret": true,
  "config": { "card_brands": ["visa", "mastercard"] }
}

Trata webhook_url como un secreto

El webhook_url devuelto autentica las llamadas del proveedor mediante un token incrustado en su query string. Cualquiera que tenga esa URL puede enviar eventos a tu conector, así que dale el mismo trato que a una API key:

• Pégala únicamente en la configuración de webhooks del propio proveedor, sobre HTTPS.
• Nunca la incluyas en un ticket, un mensaje de chat, una captura de pantalla, una línea de log ni un bundle del lado del cliente.
• Si se filtra, rótala volviendo a registrar el conector y actualiza después la URL en el dashboard del proveedor.

GET/api/v1/merchants/:merchant_id/connectors

Devuelve una lista paginada de los conectores de proveedores de pago del merchant.

Parámetros de consulta

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/merchants/mrc_123/connectors \
  -H "Authorization: Bearer sk_live_org_…" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Ejemplo de respuesta — 200 OK

{
  "data": [
    {
      "id": "conn_9f2b71",
      "merchant_id": "mrc_123",
      "provider_slug": "provider_a",
      "payment_provider_id": "pp_1a2b3c",
      "name": "Provider A BRL",
      "country_code": "BR",
      "auth_method": "api_key",
      "is_test_mode": false,
      "is_active": true,
      "created_at": "2026-01-15T12:30:00Z",
      "webhook_url": "https://api.tokeflow.com/webhooks/connectors/conn_9f2b71?token=whsec_…",
      "has_webhook_secret": true,
      "config": { "card_brands": ["visa", "mastercard"] }
    },
    {
      "id": "conn_4d8ea0",
      "merchant_id": "mrc_123",
      "provider_slug": "provider_b",
      "name": "Provider B sandbox",
      "country_code": "BR",
      "auth_method": "api_key",
      "is_test_mode": true,
      "is_active": true,
      "created_at": "2026-01-10T09:15:00Z",
      "webhook_url": "https://api.tokeflow.com/webhooks/connectors/conn_4d8ea0?token=whsec_…",
      "has_webhook_secret": true,
      "config": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

GET/api/v1/merchants/:merchant_id/connectors/:connector_id

Recupera un único conector. Devuelve el objeto conector.

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/merchants/mrc_123/connectors/conn_9f2b71 \
  -H "Authorization: Bearer sk_live_org_…"

Ejemplo de respuesta — 200 OK

{
  "id": "conn_9f2b71",
  "merchant_id": "mrc_123",
  "provider_slug": "provider_a",
  "payment_provider_id": "pp_1a2b3c",
  "name": "Provider A BRL",
  "country_code": "BR",
  "auth_method": "api_key",
  "is_test_mode": false,
  "is_active": true,
  "created_at": "2026-01-15T12:30:00Z",
  "webhook_url": "https://api.tokeflow.com/webhooks/connectors/conn_9f2b71?token=whsec_…",
  "has_webhook_secret": true,
  "config": { "card_brands": ["visa", "mastercard"] }
}

Se devuelve un 404 (not_found_error) si el conector no existe o no pertenece al merchant.

PATCH/api/v1/merchants/:merchant_id/connectors/:connector_id

Actualiza parcialmente un conector — credenciales, etiqueta o estado de habilitación. Solo los campos siguientes pueden cambiarse; todos son opcionales.

Campos de la solicitud

Ejemplo de solicitud — rotar credenciales y renombrar

curl -X PATCH https://api.tokeflow.com/api/v1/merchants/mrc_123/connectors/conn_9f2b71 \
  -H "Authorization: Bearer sk_live_org_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Provider A BRL prod",
    "credentials": { "api_key": "sk_live_provider_key_rotated" }
  }'

Ejemplo de respuesta — 200 OK

{
  "id": "conn_9f2b71",
  "merchant_id": "mrc_123",
  "provider_slug": "provider_a",
  "payment_provider_id": "pp_1a2b3c",
  "name": "Provider A BRL prod",
  "country_code": "BR",
  "auth_method": "api_key",
  "is_test_mode": false,
  "is_active": true,
  "created_at": "2026-01-15T12:30:00Z",
  "webhook_url": "https://api.tokeflow.com/webhooks/connectors/conn_9f2b71?token=whsec_…",
  "has_webhook_secret": true,
  "config": { "card_brands": ["visa", "mastercard"] }
}

Se devuelve un 404 (not_found_error) si el conector no existe o no pertenece al merchant.

DELETE/api/v1/merchants/:merchant_id/connectors/:connector_id

Elimina el conector. No debe estar referenciado por ningún nodo de enrutamiento ni ser el conector predeterminado de un perfil de enrutamiento — redirige esos primero.

Ejemplo de solicitud

curl -X DELETE https://api.tokeflow.com/api/v1/merchants/mrc_123/connectors/conn_4d8ea0 \
  -H "Authorization: Bearer sk_live_org_…"

Códigos de respuesta

Errores

Todo error usa el envoltorio estándar. Los casos más comunes para este recurso:

Consulta Errores para conocer el envoltorio completo y el catálogo de tipos.

Relacionados

• Proveedores de pago — descubre los proveedores conectables y sus métodos de autenticación admitidos.
• Perfiles de enrutamiento — decide qué conector atiende cada cobro.
• Transacciones — observa los conectores en acción en la cronología de enrutamiento.
• Autenticación — aprovisiona claves y alcances.