Eventos de webhook - Cadastro e Credenciamento

Durante o processo de credenciamento, a Zoop dispara webhooks para notificar o marketplace sobre mudanças de estado do seller. Os eventos seguem o padrão documentado em Notificações e eventos (Webhook).

Eventos de seller

Evento	Gatilho	Descrição
seller.created	Cadastro concluído	Um novo seller foi criado e está pendente de análise
seller.enabled	Credenciamento aprovado	Seller passou por todas as etapas e está ativo
seller.denied	Credenciamento reprovado	Seller foi negado no processo de credenciamento
seller.disabled	Seller bloqueado para novas transações	Seller foi bloqueado de realizar novas transações
seller.updated	Atualização cadastral	Dados do seller foram alterados
seller.deleted	Exclusão do seller	Seller foi removido e não pode ser mais acessado

Payload do evento seller.denied

Quando um seller é reprovado, o webhook seller.denied inclui os motivos da negação no campo decision_reasons, agora estruturado como um array de objetos. Cada objeto contém o motivo (reason) e o detalhe específico (detail). No webhook, é possível também verificar a possibilidade de retentativa (retry) de cadastro daquele seller:

{
    "id": "72304b0d62af43998a42eca62e8f7c13",
    "status": "denied",
    "resource": "seller",
    "account_balance": 0.0,
    "current_balance": 0.0,
    "first_name": "Teste",
    "last_name": "Cadastro",
    "email": "[email protected]",
    "taxpayer_id": "123456789",
    "phone_number": "21-99999-9998",
    "birthdate": "1990-05-15",
    "address": {
        "line1": "Rua das Flores",
        "line2": "123",
        "line3": "Apto 45",
        "neighborhood": "Centro",
        "city": "So Paulo",
        "state": "SP",
        "postal_code": "01310100",
        "country_code": "BR"
    },
    "mcc": "71",
    "show_profile_online": false,
    "is_mobile": false,
    "decline_on_fail_security_code": false,
    "decline_on_fail_zipcode": false,
    "delinquent": false,
    "marketplace_id": "1234567xyz",
    "uri": "/v1/marketplaces/1234567xyz/sellers/individuals",
    "metadata": {},
    "created_at": "2026-08-01T19:30:03+00:00",
    "updated_at": "2026-08-01T19:30:22+00:00",
    "revenue": 10000.0,
    "type": "individual",
    "decision_reasons": [
        {
            "reason": "INTERNAL_KYC_POLICY",
            "detail": "MOCKED_DETAIL"
        },
        {
            "reason": "INTERNAL_KYC_POLICY_XX",
            "detail": "MOCKED_DETAIL"
        },
        {
            "reason": "INTERNAL_KYC_POLICY_YY",
            "detail": "MOCKED_DETAIL"
        }
    ],
    "retry": true,
    "document_number": "12345678900"
}

Campos de cada item em `decision_reasons` e `retry`

Campo	Tipo	Descrição
reason	string	Categoria do motivo de negação (ex: DOCUMENT_VALIDATION, REGISTRATION_INCONSISTENCY)
detail	string	Detalhe específico associado ao motivo (ex: DOCUMENT_NOT_MATCH, NAME_INVALID)
retry	boolean	Indica se o seller pode realizar uma nova tentativa de onboarding ou as negativas não apontam possibilidade de serem aprovadas mesmo em um novo processo

Tabela de reason e detail

reason (categoria)	detail (detalhe)	Descrição
DOCUMENT_VALIDATION	DOCUMENT_NOT_MATCH	Documento ilegível ou não corresponde à pessoa da selfie enviada
DOCUMENT_VALIDATION	DOCUMENT_QUALITY	Foto do documento e/ou da Selfie com baixa qualidade, impossibilitando análise
INTERNAL_KYC_POLICY	—	Seller negado por política interna Zoop
FRAUD_PREVENTION	—	Seller negado por política interna de prevenção à fraude Zoop
REGISTRATION_INCONSISTENCY	NAME_INVALID	Nome diverge do cadastro oficial da Receita Federal
REGISTRATION_INCONSISTENCY	BIRTH_DATE_INVALID	Data de nascimento diverge do cadastro oficial da Receita Federal
REGISTRATION_INCONSISTENCY	REGISTRATION_STATUS_INVALID	CPF/CNPJ com situação irregular na Receita Federal

⚠️
Importante
O campo decision_reasons é um array de objetos — um mesmo seller pode acumular múltiplos motivos de negativa, cada um com seu próprio detail.
O campo retry indica se o seller pode realizar uma nova tentativa de onboarding, ou seja, se o(s) motivo(s) de negativa forem passíveis de correção, será indicada a possibilidade de nova tentativa de cadastro. Para nova tentativa, é necessário criar um novo seller e refazer todo o processo.

Eventos de sucesso

Quando o seller é aprovado, o webhook seller.enabled é disparado com o payload simplificado:

{
    "id": "6f2d03fcf3974abc95c2cb3ee33a111a",
    "status": "enabled",
    "resource": "seller",
    "account_balance": 0.0,
    "current_balance": 0.0,
    "first_name": "Teste",
    "last_name": "Cadastro",
    "email": "[email protected]",
    "taxpayer_id": "123456789",
    "phone_number": "21-99999-9998",
    "birthdate": "1990-05-15",
    "address": {
        "line1": "Rua das Flores",
        "line2": "123",
        "line3": "Apto 45",
        "neighborhood": "Centro",
        "city": "So Paulo",
        "state": "SP",
        "postal_code": "01310100",
        "country_code": "BR"
    },
    "mcc": "71",
    "show_profile_online": false,
    "is_mobile": false,
    "decline_on_fail_security_code": false,
    "decline_on_fail_zipcode": false,
    "delinquent": false,
    "marketplace_id": "1234567xyz",
    "uri": "/v1/marketplaces/1234567xyz/sellers/individuals",
    "metadata": {},
    "created_at": "2026-08-01T19:30:03+00:00",
    "updated_at": "2026-08-01T19:30:22+00:00",
    "revenue": 10000.0,
    "type": "individual",
    "document_number": "12345678900"
}

Fluxo típico de onboarding via webhooks

POST /sellers/individuals → seller.created
POST /sellers/{id}/documents → (envio de documentos)
Análise Zoop (até 3 min para 99% dos casos)
Resultado:
- Aprovado → seller.enabled
- Reprovado → seller.denied (com decision_reasons contendo reason, detail e retry)

Eventos de Associação de Dados Bancários

Evento	Descrição
bank_account.associated	Conta bancária associada ao customer
bank_account.deleted	Conta bancária deletada

Eventos de Atualização Cadastral Periódica

Evento	Descrição
regulatory.registration.review.required	Revisão periódica de dados cadastrais

Updated 4 days ago

Did this page help you?