Status e Reenvio
Ciclo de vida do submerchant e como tratar rejeições
Ciclo de Vida
O submerchant passa por diferentes estados desde a criação até a ativação:
Tabela de Status
| Status | Descrição | Pode transacionar? |
|---|---|---|
pending | Cadastro em edição (recém-criado ou voltou após rejeição) | Não |
pending_review | Em análise pela equipe SoarLabz | Não |
active | Aprovado e habilitado para transações | Sim |
rejected | Reprovado na análise | Não |
suspended | Temporariamente suspenso | Não |
inactive | Desativado permanentemente (uso interno) | Não |
Enviar para Análise
Após criar a subconta e completar os dados (representante legal para PJ, documentos obrigatórios, endereço), envie-a para análise:
curl -X POST https://api.payhubrasil.com.br/v1/submerchants/{id}/submit-for-review \
-H "Authorization: Basic {credentials}"O endpoint valida que o cadastro está completo antes de transicionar para pending_review. Erros comuns:
| Código | Significado |
|---|---|
MISSING_LEGAL_REPRESENTATIVE | PJ sem nenhum sócio cadastrado |
MISSING_BIRTH_DATE | PF sem birth_date |
MISSING_MOTHER_NAME | PF sem mother_name |
MISSING_DOCUMENTS | Nenhum documento ativo enviado |
INVALID_STATUS | Submerchant não está em pending |
Consultando o Status
curl -X GET https://api.payhubrasil.com.br/v1/submerchants/{id} \
-H "Authorization: Basic {credentials}"{
"message": "Submerchant encontrado com sucesso",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"trade_name": "Loja do João",
"status": "rejected",
"review_notes": "Documento de identidade ilegível",
"reviewed_at": "2026-03-18T20:00:00.000Z"
}
}Reenvio após Rejeição
Quando um submerchant é rejeitado, o fluxo é dividido em três etapas para deixar claro o ponto de edição:
Solicite o reenvio
Chame POST /v1/submerchants/{id}/request-resubmission. O status volta para pending e o histórico de análise (review_notes, reviewed_at, reviewed_by) é limpo.
Corrija os dados
Atualize documentos, endereços, sócios e dados cadastrais conforme o motivo informado em review_notes. Use os endpoints de PATCH /v1/submerchants/{id}, upload de documentos e sócios normalmente.
Envie novamente para análise
Chame POST /v1/submerchants/{id}/submit-for-review para devolver o cadastro à fila de análise.
Solicitar Reenvio
curl -X POST https://api.payhubrasil.com.br/v1/submerchants/{id}/request-resubmission \
-H "Authorization: Basic {credentials}"entity_type e tax_id permanecem imutáveis após a criação. Caso tenha errado um desses campos, remova o submerchant e cadastre novamente.
Antes de chamar submit-for-review novamente, certifique-se de que todos os documentos rejeitados foram substituídos por versões válidas. O envio com os mesmos documentos resultará em nova rejeição.
Removendo um Submerchant
Submerchants que não estão ativos podem ser removidos permanentemente:
curl -X DELETE https://api.payhubrasil.com.br/v1/submerchants/{id} \
-H "Authorization: Basic {credentials}"Submerchants com status active não podem ser removidos. Primeiro é necessário desativá-los.