Merchants

Um merchant é um negócio que você integra à sua organization. Todo recurso voltado a pagamentos no Tokeflow — clientes, transações, pedidos, catálogo, conectores — pertence a exatamente um merchant, portanto o merchant é a unidade de isolamento para dados, configuração de roteamento e escopo de chaves de API.

Esta página cobre a superfície de merchants em nível de organization: listar e integrar merchants, atualizar seus detalhes, desativá-los, ler seu histórico de atividades e gerenciar os membros (usuários do dashboard) de cada merchant. Criar um merchant também provisiona seu primeiro proprietário: você informa um primary_email, e o Tokeflow envia a essa pessoa um convite para o dashboard do merchant.

Ciclo de vida do merchant

Dois momentos do ciclo de vida merecem atenção. Primeiro, uma vez que um merchant é credenciado nas redes de cartões (para o provisionamento de tokens de rede), os campos enviados no credenciamento — name, website, mcc e o endereço — ficam fixos nas redes e não podem mais ser alterados via PATCH. Segundo, a exclusão é reservada para merchants criados por engano: um merchant com qualquer atividade é mantido para relatórios e reconciliação, e o DELETE recusa a operação com 409. Desative-o em vez disso.

O objeto de merchant

Status do merchant

Network tokens

A Tokeflow pode provisionar um network token para cada cartão salvo em um merchant, para que as credenciais armazenadas continuem funcionando após reemissões e vencimentos. O provisionamento é um opt-in explícito por merchant: network_tokens_enabled é false para um merchant novo e nada é provisionado até que você o defina como true via PATCH. Os tokens são cobrados por provisionamento, e o merchant precisa estar credenciado nas redes de cartão antes (o credenciamento acontece automaticamente quando website, mcc e o endereço estão completos). Desligar a flag interrompe novos provisionamentos; os cartões salvos continuam funcionando pelas credenciais de provedor guardadas no cadastro, que são também o que as cobranças em um clique usam.

Checkout com cartão salvo

saved_card_checkout_enabled permite que seu servidor pague uma sessão de checkout com um cartão que o cliente salvou antes — checkout_session_id mais payment_instrument_id e credential_on_file: true em POST /transactions — em vez de pedir o cartão de novo. Ele é false para todo merchant até que você o defina como true via PATCH. Ativá-lo é uma declaração de que seu servidor autentica o cliente antes de identificá-lo em uma sessão: em uma sessão, a Tokeflow nunca vê o portador do cartão, então a cobrança depende do seu login. Enquanto estiver desativado, qualquer uso de cartão salvo em uma sessão sem um card_ciphertext_id novo é recusado com 400.

Configurações que a Tokeflow pode sobrescrever

network_tokens_enabled e saved_card_checkout_enabled são configurações próprias do merchant. A Tokeflow também pode ligar ou desligar qualquer um desses recursos para uma organization inteira ou para um único merchant — por exemplo, durante a liberação gradual de um recurso — e essa configuração prevalece. O valor que você lê no merchant é, portanto, o que você escolheu, e o comportamento efetivo pode ser diferente dele. Uma requisição recusada por causa de uma configuração da Tokeflow diz isso na mensagem de erro; para que ela seja revista, entre em contato com a equipe da Tokeflow.

O objeto de endereço

O objeto de membro

Membros são os usuários do dashboard de um merchant. Um membro é uma associação: o vínculo entre uma identidade de usuário (única por e-mail dentro da sua organization) e um merchant, com um papel. A mesma pessoa pode ter associações em vários merchants.

Endpoints

GET/api/v1/merchants

Retorna uma lista paginada dos merchants pertencentes à organization autenticada. Permite filtrar por status.

Parâmetros de consulta

Exemplo de requisição

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"

Exemplo de resposta — 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
    }
  }
}

Consulte Paginação e filtragem para saber como percorrer todas as páginas.

POST/api/v1/merchants

Integra um novo merchant à sua organization. O merchant é criado com status active, e a pessoa em primary_email se torna seu primeiro proprietário: se já existir um usuário com esse e-mail na sua organization, ele recebe uma associação no novo merchant; caso contrário, uma identidade é provisionada e um e-mail de convite é enviado para que a pessoa defina uma senha. Os e-mails são comparados sem diferenciar maiúsculas de minúsculas.

Campos da requisição

Exemplo de requisição

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"
    }
  }'

Exemplo de resposta — 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 um único merchant pertencente à organization autenticada. Retorna o objeto de merchant completo.

Exemplo de requisição

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

Exemplo de resposta — 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"
}

Um 404 (not_found_error) é retornado se o merchant não existir ou não pertencer à organization autenticada.

PATCH/api/v1/merchants/:id

Atualiza um merchant. Todos os campos do corpo são opcionais; apenas os campos enviados são alterados.

Uma vez que o merchant esteja credenciado nas redes de cartões, os campos enviados no credenciamento — name, website, mcc e address — ficam fixos nas redes e não podem mais ser alterados; tentar fazê-lo retorna 409 (conflict_error). status, phone_number, business_registration_number e external_reference permanecem editáveis durante toda a vida do merchant.

Campos da requisição

Exemplo de requisição — desativar um 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" }'

Exemplo de resposta — 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

Exclui permanentemente um merchant que nunca foi usado — sem transações, pedidos, clientes, catálogo, formas de pagamento salvas, chaves de API ativas ou credenciamento na rede de cartões. Qualquer outro caso é recusado com 409, porque merchants com atividade são mantidos para relatórios e reconciliação.

Este endpoint existe para o caso de um merchant criado por engano — espere que a recusa seja o resultado mais comum. Para retirar um merchant que já tem histórico, defina seu status como inactive com PATCH em vez disso.

Exemplo de requisição

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

Códigos de resposta

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

Recupera o histórico de atividades paginado de um merchant pertencente à organization autenticada. Cada registro descreve uma ação administrativa realizada no merchant — o que mudou, por quem e quando — o que faz deste o complemento de auditoria dos endpoints acima.

Parâmetros de consulta

Exemplo de requisição

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"

Retorna 200 OK com uma lista paginada de registros de atividade, ou 404 se o merchant não existir ou não pertencer à sua organization.

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

Lista os usuários com escopo em um merchant específico. Retorna um array paginado de objetos de membro, incluindo convites pendentes.

Parâmetros de consulta

Exemplo de requisição

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"

Exemplo de resposta — 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

Convida um usuário para um merchant por e-mail. O Tokeflow localiza ou cria a identidade do usuário dentro da sua organization e adiciona uma associação no merchant com o papel informado, depois envia um e-mail de convite para que o destinatário defina uma senha. Se a pessoa já tiver uma identidade na sua organization (de outro merchant, por exemplo), essa identidade é reutilizada — o endereço de e-mail é a identidade.

Campos da requisição

Exemplo de requisição

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"
  }'

Exemplo de resposta — 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"
}

O membro permanece pending até que o convite seja aceito. Se ele expirar antes, reenvie-o.

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

Atualiza o papel de um usuário dentro de um merchant.

Campos da requisição

Exemplo de requisição

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" }'

Retorna 204 No Content em caso de sucesso. Sem corpo na resposta.

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

Remove um usuário de um merchant. Apenas a associação é removida — a identidade de usuário subjacente mantém quaisquer associações que possua em outros merchants na sua organization.

Exemplo de requisição

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

Retorna 204 No Content em caso de sucesso. Sem corpo na resposta.

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

Reenvia um convite pendente do merchant. O token do convite e sua expiração são rotacionados — o link antigo do e-mail deixa de funcionar — e o e-mail de convite é enviado novamente. Retorna 409 (conflict_error) se o usuário já tiver aceitado.

Exemplo de requisição

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

Exemplo de resposta — 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"
}

Observe o invitation_expires_at atualizado — a contagem regressiva reinicia a partir do reenvio.

Erros

Todo erro usa o envelope padrão. Os casos mais comuns para este recurso:

Consulte Erros para o envelope completo e o catálogo de tipos.

Relacionados

• Autenticação — chaves e escopos de Organization vs. Merchant.
• Paginação e filtragem — percorra endpoints de listagem com segurança.
• Clientes — registros de compradores com escopo em um merchant.
• Transações — cobranças processadas em nome de um merchant.