Merchants

Un merchant es un negocio que incorporas bajo tu organization. Todo recurso orientado a pagos en Tokeflow — clientes, transacciones, pedidos, catálogo, conectores — pertenece exactamente a un merchant, por lo que el merchant es la unidad de aislamiento para los datos, la configuración de enrutamiento y el alcance de las claves de API.

Esta página cubre la superficie de merchants a nivel de organization: listar e incorporar merchants, actualizar sus datos, retirarlos, consultar su historial de actividad y gestionar los miembros (usuarios del dashboard) de cada merchant. Crear un merchant también aprovisiona a su primer propietario: proporcionas un primary_email, y Tokeflow le envía a esa persona una invitación al dashboard del merchant.

Ciclo de vida del merchant

Dos momentos del ciclo de vida merecen atención. Primero, una vez que un merchant está inscrito en las redes de tarjetas (para el aprovisionamiento de tokens de red), los campos enviados en la inscripción — name, website, mcc y la dirección — quedan fijos en las redes y ya no se pueden modificar mediante PATCH. Segundo, la eliminación está reservada para merchants creados por error: un merchant con cualquier actividad se conserva para fines de reporte y conciliación, y DELETE la rechaza con 409. Desactívalo en su lugar.

El objeto de merchant

Estado del merchant

Network tokens

Tokeflow puede aprovisionar un network token para cada tarjeta guardada bajo un merchant, de modo que las credenciales almacenadas sigan funcionando tras reemisiones y caducidades. El aprovisionamiento es un opt-in explícito por merchant: network_tokens_enabled es false para un merchant nuevo y no se aprovisiona nada hasta que lo pones en true mediante PATCH. Los tokens se facturan por aprovisionamiento, y el merchant debe estar inscrito antes en las redes de tarjetas (la inscripción ocurre automáticamente cuando website, mcc y la dirección están completos). Desactivar la bandera detiene los nuevos aprovisionamientos; las tarjetas guardadas siguen funcionando mediante las credenciales del proveedor conservadas en el registro, que es también lo que usan los cargos en un clic.

Checkout con tarjeta guardada

saved_card_checkout_enabled permite que tu servidor pague una sesión de checkout con una tarjeta que el cliente guardó antes — checkout_session_id más payment_instrument_id y credential_on_file: true en POST /transactions — en lugar de volver a pedir la tarjeta. Es false para todos los merchants hasta que lo pones en true mediante PATCH. Activarlo equivale a declarar que tu servidor autentica al cliente antes de identificarlo en una sesión: en una sesión, Tokeflow nunca ve al titular de la tarjeta, así que el cobro se apoya en tu inicio de sesión. Mientras está desactivado, cualquier uso de una tarjeta guardada en una sesión sin un card_ciphertext_id nuevo se rechaza con 400.

Configuraciones que Tokeflow puede anular

network_tokens_enabled y saved_card_checkout_enabled son configuraciones propias del merchant. Tokeflow también puede activar o desactivar cualquiera de las dos funciones para toda una organization o para un solo merchant — por ejemplo, mientras una función se está desplegando —, y esa configuración prevalece. Por eso, el valor que lees en el merchant es el que tú elegiste, y el comportamiento efectivo puede ser distinto. Una solicitud rechazada por una configuración de Tokeflow lo indica en su mensaje de error; para que la revisen, contacta al equipo de Tokeflow.

El objeto de dirección

El objeto de miembro

Los miembros son los usuarios del dashboard de un merchant. Un miembro es una membresía: el vínculo entre una identidad de usuario (única por correo electrónico dentro de tu organization) y un merchant, con un rol. La misma persona puede tener membresías en varios merchants.

Endpoints

GET/api/v1/merchants

Devuelve una lista paginada de los merchants pertenecientes a la organization autenticada. Permite filtrar por estado.

Parámetros de consulta

Ejemplo de solicitud

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

Ejemplo de respuesta — 200 OK

{
  "data": [
    {
      "id": "mrc_123",
      "organization_id": "org_123",
      "name": "John's Store",
      "slug": "johns-store",
      "external_reference": "internal_id_99",
      "business_registration_number": "12345678000199",
      "mcc": "5732",
      "phone_number": "+5511999990000",
      "address": {
        "line_1": "Av Paulista, 1000",
        "line_2": "Conj 42",
        "zip_code": "01310-100",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
      },
      "website": "https://johnsstore.com.br",
      "network_tokens_enabled": false,
      "saved_card_checkout_enabled": false,
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-11-28T12:10:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 6,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  }
}

Consulta Paginación y filtrado para saber cómo recorrer todas las páginas.

POST/api/v1/merchants

Incorpora un nuevo merchant bajo tu organization. El merchant se crea con estado active, y la persona en primary_email se convierte en su primer propietario: si ya existe un usuario con ese correo en tu organization, obtiene una membresía en el nuevo merchant; de lo contrario, se aprovisiona una identidad y se envía un correo de invitación para que pueda establecer una contraseña. Los correos se comparan sin distinguir mayúsculas de minúsculas.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/merchants \
  -H "Authorization: Bearer sk_live_org_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John'\''s Store",
    "primary_email": "owner@johnsstore.com",
    "primary_name": "John Smith",
    "external_reference": "internal_id_99",
    "business_registration_number": "12345678000199",
    "mcc": "5732",
    "website": "https://johnsstore.com.br",
    "phone_number": "+55 11 99999-0000",
    "address": {
      "line_1": "Av Paulista, 1000",
      "zip_code": "01310-100",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR"
    }
  }'

Ejemplo de respuesta — 201 Created

{
  "id": "mrc_123",
  "organization_id": "org_123",
  "name": "John's Store",
  "slug": "johns-store",
  "external_reference": "internal_id_99",
  "status": "active",
  "created_at": "2025-11-28T12:10:00Z"
}

GET/api/v1/merchants/:id

Recupera un único merchant perteneciente a la organization autenticada. Devuelve el objeto de merchant completo.

Ejemplo de solicitud

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

Ejemplo de respuesta — 200 OK

{
  "id": "mrc_123",
  "organization_id": "org_123",
  "name": "John's Store",
  "slug": "johns-store",
  "external_reference": "internal_id_99",
  "business_registration_number": "12345678000199",
  "mcc": "5732",
  "phone_number": "+5511999990000",
  "address": {
    "line_1": "Av Paulista, 1000",
    "line_2": "Conj 42",
    "zip_code": "01310-100",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  },
  "website": "https://johnsstore.com.br",
  "network_tokens_enabled": false,
  "saved_card_checkout_enabled": false,
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Se devuelve un 404 (not_found_error) si el merchant no existe o no pertenece a la organization autenticada.

PATCH/api/v1/merchants/:id

Actualiza un merchant. Todos los campos del cuerpo son opcionales; solo se modifican los campos que envíes.

Una vez que el merchant está inscrito en las redes de tarjetas, los campos enviados en la inscripción — name, website, mcc y address — quedan fijos en las redes y ya no se pueden modificar; intentarlo devuelve 409 (conflict_error). status, phone_number, business_registration_number y external_reference siguen siendo editables durante toda la vida del merchant.

Campos de la solicitud

Ejemplo de solicitud — desactivar un merchant

curl -X PATCH https://api.tokeflow.com/api/v1/merchants/mrc_123 \
  -H "Authorization: Bearer sk_live_org_…" \
  -H "Content-Type: application/json" \
  -d '{ "status": "inactive" }'

Ejemplo de respuesta — 200 OK

{
  "id": "mrc_123",
  "organization_id": "org_123",
  "name": "John's Store",
  "slug": "johns-store",
  "external_reference": "internal_id_99",
  "business_registration_number": "12345678000199",
  "mcc": "5732",
  "phone_number": "+5511999990000",
  "address": {
    "line_1": "Av Paulista, 1000",
    "line_2": "Conj 42",
    "zip_code": "01310-100",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  },
  "website": "https://johnsstore.com.br",
  "network_tokens_enabled": false,
  "saved_card_checkout_enabled": false,
  "status": "inactive",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-11-28T14:00:00Z"
}

DELETE/api/v1/merchants/:id

Elimina permanentemente un merchant que nunca se haya usado — sin transacciones, pedidos, clientes, catálogo, métodos de pago guardados, claves de API activas ni inscripción en la red de tarjetas. Cualquier otro caso se rechaza con 409, porque los merchants con actividad se conservan para fines de reporte y conciliación.

Este endpoint existe para el caso de un merchant creado por error — espera que el rechazo sea el resultado más común. Para retirar un merchant que ya tiene historial, establece su estado como inactive con PATCH en su lugar.

Ejemplo de solicitud

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

Códigos de respuesta

GET/api/v1/merchants/:id/activity

Recupera el historial de actividad paginado de un merchant perteneciente a la organization autenticada. Cada registro describe una acción administrativa realizada sobre el merchant — qué cambió, quién lo hizo y cuándo — lo que convierte a este endpoint en el complemento de auditoría de los endpoints anteriores.

Parámetros de consulta

Ejemplo de solicitud

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

Devuelve 200 OK con una lista paginada de registros de actividad, o 404 si el merchant no existe o no pertenece a tu organization.

GET/api/v1/merchants/:merchant_id/members

Enumera los usuarios con alcance en un merchant específico. Devuelve un array paginado de objetos de miembro, incluidas las invitaciones pendientes.

Parámetros de consulta

Ejemplo de solicitud

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

Ejemplo de respuesta — 200 OK

{
  "data": [
    {
      "membership_id": "mum_5e8d21",
      "user_id": "usr_3c9f10",
      "email": "owner@johnsstore.com",
      "name": "John Smith",
      "role": "owner",
      "joined_at": "2025-11-28T12:10:00Z",
      "status": "active",
      "invitation_expires_at": null
    },
    {
      "membership_id": "mum_7a4b90",
      "user_id": "usr_b81c22",
      "email": "team@johnsstore.com",
      "name": "team@johnsstore.com",
      "role": "admin",
      "joined_at": "2025-12-01T09:00:00Z",
      "status": "pending",
      "invitation_expires_at": "2025-12-08T09:00:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  }
}

POST/api/v1/merchants/:merchant_id/members

Invita a un usuario a un merchant por correo electrónico. Tokeflow busca o crea la identidad del usuario dentro de tu organization y agrega una membresía en el merchant con el rol indicado, luego envía un correo de invitación para que el destinatario pueda establecer una contraseña. Si la persona ya tiene una identidad en tu organization (de otro merchant, por ejemplo), esa identidad se reutiliza — la dirección de correo electrónico es la identidad.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_123/members \
  -H "Authorization: Bearer sk_live_org_…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "team@johnsstore.com",
    "name": "Store Team",
    "role": "admin"
  }'

Ejemplo de respuesta — 201 Created

{
  "membership_id": "mum_7a4b90",
  "user_id": "usr_b81c22",
  "email": "team@johnsstore.com",
  "name": "Store Team",
  "role": "admin",
  "joined_at": "2025-12-01T09:00:00Z",
  "status": "pending",
  "invitation_expires_at": "2025-12-08T09:00:00Z"
}

El miembro permanece pending hasta que se acepte la invitación. Si expira antes, reenvíala.

PATCH/api/v1/merchants/:merchant_id/members/:membership_id

Actualiza el rol de un usuario dentro de un merchant.

Campos de la solicitud

Ejemplo de solicitud

curl -X PATCH https://api.tokeflow.com/api/v1/merchants/mrc_123/members/mum_7a4b90 \
  -H "Authorization: Bearer sk_live_org_…" \
  -H "Content-Type: application/json" \
  -d '{ "role": "viewer" }'

Devuelve 204 No Content en caso de éxito. Sin cuerpo en la respuesta.

DELETE/api/v1/merchants/:merchant_id/members/:membership_id

Elimina a un usuario de un merchant. Solo se elimina la membresía — la identidad de usuario subyacente conserva cualquier membresía que tenga en otros merchants de tu organization.

Ejemplo de solicitud

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

Devuelve 204 No Content en caso de éxito. Sin cuerpo en la respuesta.

POST/api/v1/merchants/:merchant_id/members/:membership_id/resend

Reenvía una invitación pendiente del merchant. El token de la invitación y su vencimiento se rotan — el enlace anterior del correo deja de funcionar — y se envía nuevamente el correo de invitación. Devuelve 409 (conflict_error) si el usuario ya la aceptó.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_123/members/mum_7a4b90/resend \
  -H "Authorization: Bearer sk_live_org_…"

Ejemplo de respuesta — 200 OK

{
  "membership_id": "mum_7a4b90",
  "user_id": "usr_b81c22",
  "email": "team@johnsstore.com",
  "name": "Store Team",
  "role": "admin",
  "joined_at": "2025-12-01T09:00:00Z",
  "status": "pending",
  "invitation_expires_at": "2025-12-15T10:00:00Z"
}

Observa el invitation_expires_at actualizado — la cuenta regresiva se reinicia a partir del reenvío.

Errores

Todos los errores usan el sobre estándar. Los casos más comunes para este recurso:

Consulta Errores para ver el sobre completo y el catálogo de tipos.

Relacionados

• Autenticación — claves y alcances de Organization vs. Merchant.
• Paginación y filtrado — recorre endpoints de listado de forma segura.
• Clientes — registros de compradores con alcance en un merchant.
• Transacciones — cargos procesados en nombre de un merchant.