Conectores de la Organization

Consulta y gestiona los conectores de proveedor de pago entre los Merchants de la Organization desde el Dashboard.

Estos endpoints le dan a la Organization una vista entre Merchants de los conectores — la conexión de cada Merchant con un proveedor de pago. Desde aquí, un administrador de la Organization puede revisar la cobertura y gestionar los conectores sin cambiar de Merchant en Merchant.

Un conector sigue perteneciendo a exactamente un Merchant; la vista de la Organization simplemente los agrega. Desactivar uno lo saca del enrutamiento de ese Merchant de inmediato.

Estos endpoints impulsan la interfaz del Tokeflow Dashboard a nivel de la Organization. Están autenticados por sesión (JWT bearer) — el token proviene de iniciar sesión en el Dashboard, no de una clave de API sk_/pk_. Las solicitudes también incluyen el header x-organization-id, y el usuario que inició sesión debe ser miembro de esa Organization.

El objeto de conector

Devuelto por los endpoints de listado y obtención de esta página.

Campo	Tipo	Descripción
`id`	string	ID del conector.
`merchant_id`	string	ID del Merchant.
`provider_slug`	string	Slug del proveedor de pago.
`payment_provider_id`	string	ID del proveedor de pago detrás del conector — se puede seguir leyendo después de que el proveedor deje de figurar como activo.
`name`	string	Nombre del conector.
`country_code`	string \| null	Código de país ISO 3166-1 alpha-2.
`auth_method`	string	Método de autenticación (api_key para V1).
`is_test_mode`	boolean	Si este es un conector en modo de prueba.
`is_active`	boolean	Si el conector está activo.
`created_at`	string	Marca de tiempo de creación del conector. (ISO 8601 UTC).
`webhook_url`	string \| null	URL del webhook para recibir eventos del PSP. Configúrala en el dashboard de tu PSP.
`has_webhook_secret`	boolean	Si los webhooks entrantes del proveedor pueden verificarse — hay un `webhook_secret` almacenado, o el proveedor firma con una clave que ya está en `credentials` (algunos proveedores firman con la clave secreta de la cuenta).
`config`	object \| null	Configuración opcional no sensible por conector (por ejemplo, override de card_brands). Nulo cuando no hay overrides definidos, en cuyo caso el SDK recurre al default_supported_card_brands del PSP. También admite `installments_enabled` — consulta Configuración del conector.

Endpoints

GET`/api/v1/org/connectors`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Lista los conectores del Merchant.

Parámetros de consulta

Campo	Tipo	Obligatorio	Descripción
`page`	number	No	Número de página (indexado desde 1). Predeterminado `1`, mín. `1`.
`limit`	number	No	Número de elementos por página. Predeterminado `20`, mín. `1`, máx. `100`.

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/org/connectors \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Ejemplo de respuesta — 200

{
  "data": [
    {
      "id": "conn_123abc...",
      "merchant_id": "mrc_123",
      "provider_slug": "provider_a",
      "name": "Provider A BRL",
      "country_code": "BR",
      "auth_method": "api_key",
      "is_test_mode": false,
      "is_active": true,
      "created_at": "2025-11-20T10:00:00Z",
      "webhook_url": "https://api.example.com/webhooks/connectors/conn_123?token=whsec_abc123",
      "has_webhook_secret": true,
      "config": {
        "card_brands": [
          "visa",
          "mastercard",
          "elo"
        ],
        "installments_enabled": true
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

POST`/api/v1/org/connectors`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Crea un nuevo conector.

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`provider_slug`	string	Sí	Slug del proveedor de pago. Uno de `provider_a`, `provider_b`, `provider_c`, `provider_d`, `provider_e`.
`name`	string	Sí	Nombre del conector.
`country_code`	string	No	Código de país ISO 3166-1 alpha-2. Admite nulo para PSPs no específicos de país.
`is_test_mode`	boolean	Sí	Si este conector está en modo de prueba.
`is_active`	boolean	No	Si el conector está activo al crearse. Predeterminado true cuando se omite. Un conector inactivo es omitido por la evaluación de enrutamiento y es rechazado por PATCH /routing/profiles/:id/default-connector. Ten en cuenta que createRoutingProfile y updateRoutingProfile actualmente no filtran por is_active, por lo que aún se puede crear un perfil con un predeterminado inactivo — los cobros sobre él luego fallan al momento de la resolución.
`credentials`	object	Sí	Credenciales específicas del proveedor para el proveedor conectado — por ejemplo, una clave de API, o un token de acceso más el país. Los campos exactos dependen del proveedor. Los valores se cifran en reposo y nunca se devuelven por completo.
`webhook_secret`	string	No	Secreto de firma de webhook del PSP para verificar webhooks entrantes. El formato depende del proveedor: el Provider A usa `whsec_...`; el Provider B espera un objeto JSON en string `{"username":"...","password":"..."}` usado para la verificación HTTP Basic Auth; algunos proveedores esperan el token de acceso definido en el webhook en su panel, y otros no necesitan ninguno (firman con la clave secreta de la cuenta).
`config`	object	No	Configuración opcional no sensible por conector. Admite `card_brands` (restringe las marcas expuestas al SDK) e `installments_enabled` (`true` ofrece cuotas en el checkout, `false` las rechaza, sin definir acepta solo cuotas pedidas por API). Consulta Configuración del conector.
`auth_method`	string	Sí	Uno de `api_key`, `oauth2`.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/org/connectors \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_slug": "provider_a",
    "name": "Main Payment Processor",
    "country_code": "BR",
    "is_test_mode": false,
    "is_active": true,
    "credentials": {
      "api_key": "sk_test_123456789"
    },
    "webhook_secret": "whsec_abc123...",
    "config": {
      "card_brands": [
        "visa",
        "mastercard",
        "elo"
      ],
      "installments_enabled": true
    },
    "auth_method": "api_key"
  }'

Ejemplo de respuesta — 201

{
  "id": "conn_123abc...",
  "merchant_id": "mrc_123",
  "provider_slug": "provider_a",
  "name": "Provider A BRL",
  "country_code": "BR",
  "auth_method": "api_key",
  "is_test_mode": false,
  "is_active": true,
  "created_at": "2025-11-20T10:00:00Z",
  "webhook_url": "https://api.example.com/webhooks/connectors/conn_123?token=whsec_abc123",
  "has_webhook_secret": true,
  "config": {
    "card_brands": [
      "visa",
      "mastercard",
      "elo"
    ],
    "installments_enabled": true
  }
}

DELETE`/api/v1/org/connectors/:connector_id`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Elimina un conector.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`connector_id`	string	Sí	—

Ejemplo de solicitud

curl -X DELETE https://api.tokeflow.com/api/v1/org/connectors/conn_a1b2c3d4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Ejemplo de respuesta — 204 No Content

Se devuelve un cuerpo vacío cuando la operación se realiza correctamente.

GET`/api/v1/org/connectors/:connector_id`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Obtiene el conector por ID.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`connector_id`	string	Sí	—

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/org/connectors/conn_a1b2c3d4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Ejemplo de respuesta — 200

{
  "id": "conn_123abc...",
  "merchant_id": "mrc_123",
  "provider_slug": "provider_a",
  "name": "Provider A BRL",
  "country_code": "BR",
  "auth_method": "api_key",
  "is_test_mode": false,
  "is_active": true,
  "created_at": "2025-11-20T10:00:00Z",
  "webhook_url": "https://api.example.com/webhooks/connectors/conn_123?token=whsec_abc123",
  "has_webhook_secret": true,
  "config": {
    "card_brands": [
      "visa",
      "mastercard",
      "elo"
    ],
    "installments_enabled": true
  }
}

PATCH`/api/v1/org/connectors/:connector_id`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Actualiza un conector.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`connector_id`	string	Sí	—

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`name`	string	No	Nombre del conector.
`is_active`	boolean	No	Si el conector está activo.
`credentials`	object	No	Credenciales específicas del proveedor para el proveedor conectado — por ejemplo, una clave de API, o un token de acceso más el país. Los campos exactos dependen del proveedor. Los valores se cifran en reposo y nunca se devuelven por completo.
`webhook_secret`	string	No	Secreto de firma de webhook del PSP para verificar webhooks entrantes. El formato depende del proveedor: el Provider A usa `whsec_...`; el Provider B espera un objeto JSON en string `{"username":"...","password":"..."}` usado para la verificación HTTP Basic Auth; algunos proveedores esperan el token de acceso definido en el webhook en su panel, y otros no necesitan ninguno (firman con la clave secreta de la cuenta).
`config`	object	No	Configuración opcional no sensible por conector. Fusionada clave a clave. Pasa un array vacío u omite `card_brands` para limpiar el override de marcas; pasa `installments_enabled: null` para devolver las cuotas al estado sin definir. Consulta Configuración del conector.

Ejemplo de solicitud

curl -X PATCH https://api.tokeflow.com/api/v1/org/connectors/conn_a1b2c3d4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Provider A BRL Prod",
    "is_active": false,
    "credentials": {
      "api_key": "sk_live_provider_key_rotated",
      "account_id": "acct_456"
    },
    "webhook_secret": "whsec_abc123...",
    "config": {
      "card_brands": [
        "visa",
        "mastercard",
        "elo"
      ],
      "installments_enabled": true
    }
  }'

Ejemplo de respuesta — 200

{
  "id": "conn_123abc...",
  "merchant_id": "mrc_123",
  "provider_slug": "provider_a",
  "name": "Provider A BRL",
  "country_code": "BR",
  "auth_method": "api_key",
  "is_test_mode": false,
  "is_active": true,
  "created_at": "2025-11-20T10:00:00Z",
  "webhook_url": "https://api.example.com/webhooks/connectors/conn_123?token=whsec_abc123",
  "has_webhook_secret": true,
  "config": {
    "card_brands": [
      "visa",
      "mastercard",
      "elo"
    ],
    "installments_enabled": true
  }
}

POST`/api/v1/org/connectors/:connector_id/test`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Prueba las credenciales del conector contra el PSP.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`connector_id`	string	Sí	—

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/org/connectors/conn_a1b2c3d4/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

GET`/api/v1/org/connectors/:connector_id/webhooks/inbounds`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Obtiene los eventos de webhook entrantes de un conector.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`connector_id`	string	Sí	—

Parámetros de consulta

Campo	Tipo	Obligatorio	Descripción
`page`	number	No	Número de página (indexado desde 1). Predeterminado `1`, mín. `1`.
`limit`	number	No	Número de elementos por página. Predeterminado `20`, mín. `1`, máx. `100`.
`status`	string	No	Filtrar por estado del evento de webhook
`from`	string	No	Límite inferior inclusivo para received_at (ISO 8601)
`to`	string	No	Límite superior inclusivo para received_at (ISO 8601)

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/org/connectors/conn_a1b2c3d4/webhooks/inbounds \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=pending" \
  --data-urlencode "from=2026-04-01T00:00:00Z"

GET`/api/v1/org/connectors/:connector_id/webhooks/invalid`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Obtiene los eventos de webhook inválidos de un conector.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`connector_id`	string	Sí	—

Parámetros de consulta

Campo	Tipo	Obligatorio	Descripción
`page`	number	No	Número de página (indexado desde 1). Predeterminado `1`, mín. `1`.
`limit`	number	No	Número de elementos por página. Predeterminado `20`, mín. `1`, máx. `100`.
`from`	string	No	Límite inferior inclusivo para received_at (ISO 8601)
`to`	string	No	Límite superior inclusivo para received_at (ISO 8601)

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/org/connectors/conn_a1b2c3d4/webhooks/invalid \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "from=2026-04-01T00:00:00Z" \
  --data-urlencode "to=2026-04-30T23:59:59Z"

Errores

Los errores usan el envoltorio estándar. Los casos más comunes aquí:

HTTP	Significado
`400`	Parámetros inválidos o un estado que no permite esta operación.
`401`	Token de sesión del Dashboard ausente, expirado o inválido.
`403`	Autenticado, pero el usuario que inició sesión no tiene acceso a esta entidad.
`404`	El registro no existe o no es visible para esta entidad.

Conectores de la Organization

El objeto de conector

Endpoints

GET`/api/v1/org/connectors`

POST`/api/v1/org/connectors`

DELETE`/api/v1/org/connectors/:connector_id`

GET`/api/v1/org/connectors/:connector_id`

PATCH`/api/v1/org/connectors/:connector_id`

POST`/api/v1/org/connectors/:connector_id/test`

GET`/api/v1/org/connectors/:connector_id/webhooks/inbounds`

GET`/api/v1/org/connectors/:connector_id/webhooks/invalid`

Errores

Relacionados

En esta página

Conectores de la Organization

El objeto de conector

Endpoints

GET/api/v1/org/connectors

POST/api/v1/org/connectors

DELETE/api/v1/org/connectors/:connector_id

GET/api/v1/org/connectors/:connector_id

PATCH/api/v1/org/connectors/:connector_id

POST/api/v1/org/connectors/:connector_id/test

GET/api/v1/org/connectors/:connector_id/webhooks/inbounds

GET/api/v1/org/connectors/:connector_id/webhooks/invalid

Errores

Relacionados

En esta página

GET`/api/v1/org/connectors`

POST`/api/v1/org/connectors`

DELETE`/api/v1/org/connectors/:connector_id`

GET`/api/v1/org/connectors/:connector_id`

PATCH`/api/v1/org/connectors/:connector_id`

POST`/api/v1/org/connectors/:connector_id/test`

GET`/api/v1/org/connectors/:connector_id/webhooks/inbounds`

GET`/api/v1/org/connectors/:connector_id/webhooks/invalid`