tokeflow.com
DocumentaciónReferencia de APIDashboardsSDKsRegistro de cambios

Conectores del Merchant

Gestiona las conexiones de un Merchant con proveedores de pago desde el Dashboard — añade credenciales, activa o desactiva un conector y elimina uno.

Un conector es la conexión de un único Merchant con un proveedor de pago: las credenciales, el entorno al que apunta y si está actualmente habilitado. Estos endpoints respaldan la pantalla de conectores del Dashboard.

Los conectores son aquello a lo que apuntan las reglas de enrutamiento — un perfil de enrutamiento solo puede enviar un cargo a un proveedor para el que este Merchant tenga un conector. Desactivar un conector lo retira del enrutamiento de inmediato, de modo que los cargos que habrían ido a él se derivan en cascada a la siguiente opción elegible.

Estos endpoints impulsan la interfaz del Tokeflow Dashboard. 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-merchant-id, que identifica al Merchant en contexto, y el usuario que inició sesión debe ser miembro con acceso a él.

El objeto conector

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

CampoTipoDescripción
idstringID del conector.
merchant_idstringID del Merchant.
provider_slugstringSlug del proveedor de pago.
payment_provider_idstringID del proveedor de pago detrás del conector — se puede seguir leyendo después de que el proveedor deje de figurar como activo.
namestringNombre del conector.
country_codestring | nullCódigo de país ISO 3166-1 alpha-2.
auth_methodstringMétodo de autenticación (api_key para la V1).
is_test_modebooleanSi este es un conector en modo de prueba.
is_activebooleanSi el conector está activo.
created_atstringTimestamp de creación del conector. (ISO 8601 UTC).
webhook_urlstring | nullURL de webhook para recibir eventos del PSP. Configúralo en el dashboard de tu PSP.
has_webhook_secretbooleanSi 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).
configobject | nullConfiguración opcional no sensible por conector (por ejemplo, un override de card_brands). Null 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/merchant/connectors

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Lista los conectores del Merchant.

Parámetros de consulta

CampoTipoObligatorioDescripción
pagenumberNoNúmero de página (indexado desde 1). Predeterminado 1, mín. 1.
limitnumberNoNú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/merchant/connectors \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

POST/api/v1/merchant/connectors

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Crea un conector.

Campos de la solicitud

CampoTipoObligatorioDescripción
provider_slugstringSíSlug del proveedor de pago. Uno de provider_a, provider_b, provider_c, provider_d, provider_e.
namestringSíNombre del conector.
country_codestringNoCódigo de país ISO 3166-1 alpha-2. Puede ser null para PSPs no específicos de país.
is_test_modebooleanSíSi este conector está en modo de prueba.
is_activebooleanNoSi el conector está activo al crearse. Predeterminado true cuando se omite. Un conector inactivo se omite en 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 cargos en él fallan entonces en el momento de la resolución.
credentialsobjectSí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_secretstringNoSecreto de firma de webhook del PSP para verificar los webhooks entrantes. El formato depende del proveedor: el Provider A usa whsec_...; el Provider B espera un objeto JSON en cadena {"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).
configobjectNoConfiguració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_methodstringSíUno de api_key, oauth2.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/merchant/connectors \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -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/merchant/connectors/:id

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Elimina un conector.

Parámetros de ruta

CampoTipoObligatorioDescripción
idstringSí—

Ejemplo de solicitud

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/connectors/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

GET/api/v1/merchant/connectors/:id

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Obtiene un conector por ID.

Parámetros de ruta

CampoTipoObligatorioDescripción
idstringSí—

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/merchant/connectors/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

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/merchant/connectors/:id

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Actualiza un conector.

Parámetros de ruta

CampoTipoObligatorioDescripción
idstringSí—

Campos de la solicitud

CampoTipoObligatorioDescripción
namestringNoNombre del conector.
is_activebooleanNoSi el conector está activo.
credentialsobjectNoCredenciales 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_secretstringNoSecreto de firma de webhook del PSP para verificar los webhooks entrantes. El formato depende del proveedor: el Provider A usa whsec_...; el Provider B espera un objeto JSON en cadena {"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).
configobjectNoConfiguració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/merchant/connectors/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -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/merchant/connectors/:id/test

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Prueba las credenciales del conector contra el PSP.

Parámetros de ruta

CampoTipoObligatorioDescripción
idstringSí—

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/merchant/connectors/obj_1a2b3c4d/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

GET/api/v1/merchant/connectors/:id/webhooks/inbounds

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Obtiene los webhooks entrantes de un conector.

Parámetros de ruta

CampoTipoObligatorioDescripción
idstringSí—

Parámetros de consulta

CampoTipoObligatorioDescripción
pagenumberNoNúmero de página (indexado desde 1). Predeterminado 1, mín. 1.
limitnumberNoNúmero de elementos por página. Predeterminado 20, mín. 1, máx. 100.
statusstringNoFiltra por estado del evento de webhook
fromstringNoLímite inferior inclusivo para received_at (ISO 8601)
tostringNoLímite superior inclusivo para received_at (ISO 8601)

Ejemplo de solicitud

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

GET/api/v1/merchant/connectors/:id/webhooks/invalid

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

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

Parámetros de ruta

CampoTipoObligatorioDescripción
idstringSí—

Parámetros de consulta

CampoTipoObligatorioDescripción
pagenumberNoNúmero de página (indexado desde 1). Predeterminado 1, mín. 1.
limitnumberNoNúmero de elementos por página. Predeterminado 20, mín. 1, máx. 100.
fromstringNoLímite inferior inclusivo para received_at (ISO 8601)
tostringNoLímite superior inclusivo para received_at (ISO 8601)

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/merchant/connectors/obj_1a2b3c4d/webhooks/invalid \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --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í:

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

Relacionados

Registro de auditoría del Merchant

Anterior

Clientes del Merchant

Siguiente

En esta página

El objeto conectorEndpointsGET /api/v1/merchant/connectorsPOST /api/v1/merchant/connectorsDELETE /api/v1/merchant/connectors/:idGET /api/v1/merchant/connectors/:idPATCH /api/v1/merchant/connectors/:idPOST /api/v1/merchant/connectors/:id/testGET /api/v1/merchant/connectors/:id/webhooks/inboundsGET /api/v1/merchant/connectors/:id/webhooks/invalidErroresRelacionados