Clientes do Merchant

Esses endpoints dão suporte à tela de clientes do Dashboard para um único Merchant: listar pagadores com busca e filtros, abrir um deles para ver todos os detalhes e atualizar ou remover um registro.

Um cliente agrupa tudo o que um pagador possui dentro deste Merchant — instrumentos de pagamento salvos, pedidos e assinaturas. Os clientes nunca cruzam os limites de um Merchant, então a mesma pessoa comprando em dois dos seus Merchants é dois registros de cliente separados.

O objeto cliente

Retornado pelos endpoints de listagem e recuperação desta página.

Endpoints

GET/api/v1/merchant/customers

Lista os clientes do Merchant.

Parâmetros de consulta

Exemplo de solicitação

curl -G https://api.tokeflow.com/api/v1/merchant/customers \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "merchant_id=mrc_8a3f12d9" \
  --data-urlencode "search=string"

DELETE/api/v1/merchant/customers/:id

Exclui permanentemente um cliente. Cancela todas as assinaturas que ainda não estejam canceladas ou expiradas, revoga todos os métodos de pagamento salvos — removendo os dados do cartão armazenados — e então desativa o cliente. Isso não pode ser desfeito. O cliente continua disponível para consulta via GET /:id, de modo que seu histórico permanece revisável, mas ele sai da lista de clientes e não pode mais ser usado em novas operações, e seu e-mail volta a ficar disponível. Note que isso difere do DELETE na superfície de chave de API (/customers/:customerId), que em vez disso recusa com 409 quando um cliente tem qualquer histórico.

Parâmetros de caminho

Exemplo de solicitação

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

Exemplo de resposta — 200

{
  "id": "cust_123",
  "object": "customer",
  "deleted": true
}

GET/api/v1/merchant/customers/:id

Obtém um cliente por ID.

Parâmetros de caminho

Exemplo de solicitação

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

Exemplo de resposta — 200

{
  "id": "obj_1a2b3c4d",
  "organization_id": "org_4b21e7c3",
  "merchant_id": "mrc_8a3f12d9",
  "merchant_name": "Acme Store",
  "name": "Jane Buyer",
  "email": "jane@example.com",
  "phone": "+5511987654321",
  "document_type": "12345678909",
  "document_number": "12345678909",
  "metadata": {},
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:00.000Z",
  "deleted": false,
  "payment_instruments": [
    {
      "id": "obj_1a2b3c4d",
      "instrument_type": "standard",
      "last4": "string",
      "brand": "string",
      "card_type": "standard",
      "exp_month": 1,
      "exp_year": 1,
      "external_wallet_id": "string",
      "status": "active",
      "is_default": true,
      "created_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "linked_subscriptions": [
    {}
  ],
  "linked_orders": [
    {
      "id": "obj_1a2b3c4d",
      "status": "active",
      "total_amount": 15000,
      "currency": "BRL",
      "created_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "external_references": [
    {
      "source_type": "standard",
      "connector_name": "Acme Store",
      "external_id": "string"
    }
  ]
}

PATCH/api/v1/merchant/customers/:id

Atualiza um cliente.

Parâmetros de caminho

Campos da solicitação

Exemplo de solicitação

curl -X PATCH https://api.tokeflow.com/api/v1/merchant/customers/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Store",
    "email": "jane@example.com",
    "phone": "+5511987654321",
    "document_type": "cpf",
    "document_number": "12345678909"
  }'

Exemplo de resposta — 200

{
  "id": "obj_1a2b3c4d",
  "organization_id": "org_4b21e7c3",
  "merchant_id": "mrc_8a3f12d9",
  "merchant_name": "Acme Store",
  "name": "Jane Buyer",
  "email": "jane@example.com",
  "phone": "+5511987654321",
  "document_type": "12345678909",
  "document_number": "12345678909",
  "metadata": {},
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:00.000Z",
  "deleted": false
}

Erros

Os erros usam o envelope padrão. Os casos mais comuns aqui:

Relacionados

• Clientes (API pública)
• Instrumentos de pagamento
• Pedidos do Merchant