Como ler as tabelas
| Coluna | Conteúdo |
|---|---|
| HTTP | Código de status da resposta |
| Mensagem ou código | Valor literal de message ou, nas rotas que usam código de negócio, o valor de code (Apple Pay e validação de cartão) ou de error (envio de documentos com token). X e Y indicam valores que variam |
| Causa | O que provoca o erro |
| Ação | O que fazer |
| Formato | Onde |
|---|---|
{ "statusCode", "message", "error" } | Padrão. Em erros de validação do corpo (400), message vem como lista, um item por problema |
{ "code", "message" } | Erros de negócio do Apple Pay e validação de cartão em POST /v1/subscriptions |
{ "error", "message", "details" } | Erros de arquivo em POST /v1/document-uploads |
Para o desenvolvedor: decida o fluxo pelo código HTTP e, quando existir, pelo
code ou pelo error dos dois últimos formatos. Use o texto de message só para log e diagnóstico: ele mistura idiomas e pode mudar.Erros comuns a todas as rotas
| HTTP | Mensagem | Causa | Ação |
|---|---|---|---|
400 | Lista em message, com error Bad Request (ex.: ["amount must not be less than 1"]) | Campo obrigatório ausente, tipo errado ou valor fora do limite | Corrija cada item da lista e envie de novo |
401 | Unauthorized | Chave inválida, cabeçalho Authorization ausente ou formato incorreto. O corpo é { "statusCode": 401, "message": "Unauthorized" } | Confira a chave, o prefixo Basic e se o Base64 decodificado termina em : |
403 | Acesso negado | O perfil do usuário que gerou a chave não tem permissão para a rota. O corpo é { "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 } | Gere a chave com um usuário Owner ou Manager. Veja Permissões da chave |
500 | Internal server error | Erro interno | Em consultas, tente de novo com espera crescente. Em criações, verifique se o recurso foi criado antes de repetir |
Cobranças
POST /v1/charges
| HTTP | Mensagem ou código | Causa | Ação |
|---|---|---|---|
400 | Shipping info must be provided for merchants selling physical items. | Algum item é physical e o corpo não traz shippingAddress. Nenhuma cobrança é criada | Envie shippingAddress com postalCode, addressLine1, city, state e country |
400 | Lista em message, ex.: ["shippingAddress.country must be a valid ISO31661 Alpha3 code"] | shippingAddress incompleto ou inválido, ou outro campo fora do contrato | Corrija os campos indicados. País em 3 letras (BRA) |
400 | CVV is required when using cardTokenId | Cobrança com cartão salvo sem cvv | Colete o CVV do comprador e envie junto com o cardTokenId |
400 | Erro de validação do cartão salvo | O cartão do cardTokenId está revogado, expirado ou pendente de ativação | Use outro cartão. Confira o status em GET /v1/cards |
403 | Acesso negado | Chave de usuário Desenvolvedor | Gere a chave com usuário Owner ou Manager |
422 | Fees not configured | A conta não tem taxa configurada para o método, a moeda ou o número de parcelas. Vale também no Modo Teste | Fale com o suporte da Finvia |
500 | Internal server error | Erro interno | Siga o procedimento de timeout antes de repetir |
201, status refused ou failed e o motivo em reason. Também sai o webhook charge.refused ou charge.failed.
reason (literal) | Causa | Ação |
|---|---|---|
card_declined | Recusa do cartão de teste 4444333322221112 no Modo Teste. Em produção, o reason traz o motivo informado pelo processador | Oferecer outro cartão ou Pix |
3ds_required: Não foi possível completar a autenticação 3DS obrigatória | A conta exige 3D Secure e a cobrança veio sem autenticação, ou o 3DS não pôde ser feito | Fazer a autenticação 3DS antes de criar a cobrança |
3ds_failed: The cardholder failed to authenticate. Please try again or use a different card | O comprador não passou na autenticação | Pedir nova tentativa ou outro cartão |
3ds_incomplete: Required authentication data (cryptogram or ECI) is missing | 3DS obrigatório e cryptogram ou eci ausentes ou null | Repassar o resultado completo de challenge-result, sem enviar campos null |
3ds_<estado>: Authentication did not succeed | No 3DS gerenciado, a autenticação não passou (<estado> é o estado final) | Pedir nova tentativa ou outro cartão |
antifraud_denied | Recusa pela análise antifraude da conta | Oferecer outra forma de pagamento |
in_analysis com reason antifraud_manual_review. Não é recusa: aguarde o desfecho.
Erros de Apple Pay nesta rota, no formato { code, message }:
| HTTP | Código | Causa | Ação |
|---|---|---|---|
400 | APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED | customer.document ausente. O token da Apple não traz CPF ou CNPJ | Coletar o documento no checkout antes de abrir o Apple Pay |
422 | APPLE_PAY_CURRENCY_NOT_SUPPORTED | Moeda diferente de BRL | Usar BRL |
400 | APPLE_PAY_TOKEN_INVALID | O objeto em wallet.token não está no formato do token da Apple | Enviar o payment.token na íntegra, sem reescrever campos |
400 | APPLE_PAY_PROVIDER_REJECTED | O processador recusou a operação ou devolveu resposta fora do contrato | Verificar o token e tentar de novo. Persistindo, falar com o suporte |
422 | APPLE_PAY_PROCESSOR_NOT_CONFIGURED | O processador de Apple Pay não está configurado para a conta | Falar com o suporte |
503 | APPLE_PAY_PROVIDER_UNAVAILABLE | Processador indisponível | Tentar de novo mais tarde |
500 | APPLE_PAY_PROVIDER_AUTH_FAILED | Falha de autenticação entre a Finvia e o processador | Falar com o suporte |
GET /v1/charges e GET /v1/charges/{id}
| HTTP | Mensagem | Causa | Ação |
|---|---|---|---|
401 | Unauthorized | Credencial inválida | Ver erros comuns |
403 | Acesso negado | Perfil sem permissão | Ver erros comuns |
GET /v1/charges/{id} com um id que não existe responde hoje 200 com corpo vazio, sem 404. Trate corpo vazio como “cobrança não encontrada”. Confira também se a chave é do mesmo ambiente da cobrança: a chave de teste só enxerga cobranças de teste.POST /v1/refunds
| HTTP | Mensagem | Causa | Ação |
|---|---|---|---|
404 | Cobrança não encontrada | chargeId inexistente, ou cobrança que não está paid (já estornada, pendente, pre_chargeback ou chargeback) | Consultar a cobrança antes de pedir o estorno |
422 | Já existe um reembolso para esta cobrança | Segundo pedido de estorno para a mesma cobrança | Não repetir. Cada cobrança aceita um único estorno |
501 | Reembolso não implementado para este método de pagamento | O método da cobrança não tem estorno pela API | Falar com o suporte |
501 | Reembolso não disponível para este provedor de pagamento | O provedor da cobrança não oferece estorno | Falar com o suporte |
500 | Internal server error | Erro interno | Consultar a cobrança antes de repetir |
POST /v1/charges/{id}/resend-webhook
| HTTP | Mensagem | Causa | Ação |
|---|---|---|---|
400 | Lista em message | status fora da lista aceita (paid, pending, refused, failed, refunded, in_analysis, authentication_required). pre_chargeback e chargeback não são aceitos | Usar um dos status aceitos |
403 | Redisparo de webhook disponível apenas para cobranças de teste | A cobrança foi criada com chave de produção | Usar uma cobrança criada com chave sk_test_ |
403 | Acesso negado | Perfil sem permissão | Ver erros comuns |
404 | Cobrança não encontrada | id inexistente | Conferir o id |
Apple Pay (domínios e sessão)
Erros de negócio no formato{ code, message }. Erros de validação de campo vêm no formato padrão, com message em lista, e o 403 de permissão traz Acesso negado.
| Rota | HTTP | Código | Causa | Ação |
|---|---|---|---|---|
POST /v1/apple-pay/domains | 400 | APPLE_PAY_INVALID_DOMAIN | domain não é um hostname puro (tem esquema, porta, caminho, é um IP ou passa de 255 caracteres) | Enviar só o hostname, como checkout.minhaloja.com.br |
POST /v1/apple-pay/domains | 409 | APPLE_PAY_DOMAIN_ALREADY_REGISTERED | Dois registros simultâneos do mesmo hostname | Repetir a chamada: a rota devolve o registro existente |
POST /v1/apple-pay/domains | 400 | APPLE_PAY_PROVIDER_REJECTED | O provedor recusou o registro | Verificar o hostname e tentar de novo |
POST /v1/apple-pay/domains | 403 | Acesso negado | O usuário dono da chave não tem a permissão de domínios Apple Pay (Owner, Manager e Desenvolvedor têm) | Usar a chave de um desses perfis |
POST /v1/apple-pay/domains/{id}/validate | 404 | APPLE_PAY_DOMAIN_NOT_FOUND | Domínio inexistente ou de outra conta | Conferir o id com GET /v1/apple-pay/domains |
POST /v1/apple-pay/domains/{id}/validate | 422 | APPLE_PAY_DOMAIN_VERIFICATION_FAILED | Arquivo de verificação ausente ou inacessível. O domínio vai para failed, verifiedAt volta a null e o motivo fica em lastVerificationError | Corrigir a hospedagem do arquivo e validar de novo |
GET /v1/apple-pay/domains/{id} | 404 | APPLE_PAY_DOMAIN_NOT_FOUND | Domínio inexistente ou de outra conta | Conferir o id |
POST /v1/apple-pay/validate-merchant | 400 | APPLE_PAY_INVALID_VALIDATION_URL | validationUrl não é HTTPS em host apple.com (ou subdomínio), tem porta ou passa de 2048 caracteres | Enviar o event.validationURL recebido da Apple sem alterar |
POST /v1/apple-pay/validate-merchant | 400 | APPLE_PAY_INVALID_DOMAIN | domain inválido | Enviar o window.location.hostname |
POST /v1/apple-pay/validate-merchant | 400 | APPLE_PAY_DOMAIN_NOT_VERIFIED | O domínio não é da conta da pk_, não foi registrado ou ainda não foi verificado | Registrar e verificar o hostname exato da página |
POST /v1/apple-pay/validate-merchant | 422 | APPLE_PAY_PROVIDER_NOT_ENABLED | A conta ainda não registrou nenhum domínio | Registrar o primeiro domínio |
POST /v1/apple-pay/validate-merchant | 429 | APPLE_PAY_RATE_LIMITED | Mais de 20 tentativas por IP a cada 5 minutos, ou teto global da plataforma | Aguardar e validar uma vez por clique |
| Todas as rotas de Apple Pay | 422 | APPLE_PAY_PROCESSOR_NOT_CONFIGURED | Processador de Apple Pay não configurado para a conta | Falar com o suporte |
| Todas as rotas de Apple Pay | 503 | APPLE_PAY_PROVIDER_UNAVAILABLE | Provedor indisponível | Tentar de novo mais tarde |
| Todas as rotas de Apple Pay | 500 | APPLE_PAY_PROVIDER_AUTH_FAILED | Falha de autenticação entre a Finvia e o provedor | Falar com o suporte |
Saldos e meios de pagamento
| Rota | HTTP | Mensagem | Causa | Ação |
|---|---|---|---|---|
GET /v1/wallets | 403 | Acesso negado | Chave de usuário Desenvolvedor | Gerar a chave com usuário Owner ou Manager |
GET /v1/wallets | 404 | Merchant not found (corpo { "statusCode": 404, "message": "Merchant not found", "error": "Not Found" }) | merchantId inexistente ou sem acesso | Conferir o merchantId |
GET /v1/payment-methods | 401 | Unauthorized | Credencial inválida | Ver erros comuns |
Saques
Não existe saque no Modo Teste. Os erros de regra vêm em inglês.POST /v1/payout-requests (própria conta)
| HTTP | Mensagem | Causa | Ação |
|---|---|---|---|
400 | Lista em message | Corpo inválido (campo ausente, tipo errado) | Corrigir o corpo. Não é 422 |
400 | Lista em message | currency com código ISO inválido | Enviar BRL |
403 | WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE | Pedido com a chave de teste | Saques só em produção |
403 | Acesso negado | Chave de perfil sem permissão de saque (ex.: Desenvolvedor) | Gerar a chave com usuário Owner ou Manager |
404 | Merchant not found | merchantId inexistente | Enviar o id da própria conta |
422 | Insufficient balance. Required: X, Available: Y | Saldo disponível menor que amount | Consultar o saldo antes de sacar |
422 | Maximum withdrawal amount is X | Valor acima do limite máximo por saque configurado para a conta | Dividir o saque ou falar com o suporte |
422 | You already have a pending withdrawal request for this currency | Já existe um saque pending na mesma moeda | Aguardar a decisão do saque pendente |
422 | Withdrawals are disabled for this merchant | Saques desabilitados na conta | Falar com o suporte |
422 | Saques estão desabilitados para esta conta (saldo retido por configuração administrativa) | Conta com saldo retido | Falar com o suporte |
422 | Merchant account is not active | Conta não está ativa | Falar com o suporte |
422 | Merchant settings are not configured correctly | Configuração da conta incompleta | Falar com o suporte |
422 | Payout fees not configured | Taxa de saque não configurada | Falar com o suporte |
422 | Currency X is not supported for withdrawals | Moeda válida, mas sem saque | Enviar BRL |
422 | You can only create withdrawal requests for your own account | merchantId de outra conta | Enviar o id da própria conta |
422 | Payout execution failed: ... | Falha na execução, só em contas com aprovação automática | Consultar GET /v1/payout-requests antes de repetir: o pedido pode ter ficado pending |
POST /v1/submerchants/{merchantId}/payout-requests (subconta)
| HTTP | Mensagem | Causa | Ação |
|---|---|---|---|
400 | Lista em message, ex.: ["amount must be a positive number", "amount must not be less than 1"] | amount ausente, zero ou abaixo de 1 | Enviar o valor em reais, mínimo 1 |
403 | Fast Connect not enabled. | Connect não habilitado na conta master | Pedir a habilitação |
403 | WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE | Pedido com a chave de teste | Saques só em produção |
404 | SubMerchant not found | Subconta inexistente ou de outra conta master | Conferir o merchantId |
422 | SubMerchant account is not active | Subconta não está active | Aguardar a aprovação da subconta |
422 | SubMerchant is blocked. Withdrawals are not allowed. | Subconta bloqueada | Falar com o suporte |
422 | SubMerchant CNPJ not configured | Subconta sem CNPJ cadastrado (o CNPJ é a chave Pix do saque) | Completar o cadastro da subconta |
422 | Withdrawals are disabled for this submerchant | Saques desabilitados na subconta | Falar com o suporte |
422 | Insufficient balance. Required: X, Available: Y | Saldo disponível insuficiente | Consultar o saldo antes de sacar |
422 | Maximum withdrawal amount is X BRL | Valor acima do limite por saque | Dividir o saque |
422 | You already have a pending withdrawal request for this currency | Já existe saque pending | Aguardar a decisão |
422 | Merchant settings are not configured correctly | Configuração incompleta | Falar com o suporte |
422 | Payout fees not configured | Taxa de saque não configurada | Falar com o suporte |
GET /v1/payout-requests
| HTTP | Mensagem | Causa | Ação |
|---|---|---|---|
403 | Acesso negado | Chave de usuário Desenvolvedor | Gerar a chave com usuário Owner ou Manager |
404 | Merchant not found | merchantId de uma conta sem acesso | Conferir o merchantId |
500 | Internal server error | orderBy enviado na consulta | Não envie orderBy: a ordem já é do mais recente para o mais antigo |
Clientes
| Rota | HTTP | Mensagem | Causa | Ação |
|---|---|---|---|---|
GET /v1/customers/{id} | 404 | Customer not found | id inexistente ou de outra conta | Conferir o id |
PUT /v1/customers/{id} | 404 | Customer not found | id inexistente | Conferir o id |
DELETE /v1/customers/{id} | 404 | Customer not found | id inexistente ou já removido | Conferir o id |
Cartões
| Rota | HTTP | Mensagem | Causa | Ação |
|---|---|---|---|---|
POST /v1/cards | 400 | Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador | Cliente sem e-mail, ou com documento que não tem 11 dígitos (CPF) nem 14 (CNPJ) | Usar um cliente com e-mail e CPF ou CNPJ |
POST /v1/cards | 400 | Failed to register card | Dados do cartão inválidos ou outra falha no registro | Conferir os dados do cartão |
GET /v1/cards/{id} | 404 | Card not found | id inexistente | Conferir o id |
DELETE /v1/cards/{id} | 404 | Card not found | id inexistente | Conferir o id |
3D Secure
As rotas abaixo usam a chave pública (pk_).
| Rota | HTTP | Mensagem | Causa | Ação |
|---|---|---|---|---|
/v1/three-ds/* | 401 | Unauthorized | Chave pública inválida | Usar a pk_ da conta (ou pk_test_ no sandbox) |
/v1/three-ds/* | 404 | No 3DS provider configured for this gateway | Não há provedor 3DS configurado | Falar com o suporte para habilitar o 3DS |
POST /v1/three-ds/challenge-result | 500 | Mensagem iniciada por Authentication challenge not yet completed | Chamada antes do fim do desafio | Chamar só depois do sinal de fim do desafio ou de um status final |
POST /v1/charges/{id}/resume-3ds | 400 | Cobrança não está utilizando 3DS gerenciado | A cobrança não usa o 3DS gerenciado | Não chamar esta rota fora do fluxo gerenciado |
POST /v1/charges/{id}/resume-3ds | 400 | Lista em message | threeDS ausente, null ou com type ou state null | Enviar o objeto threeDS completo |
POST /v1/charges/{id}/resume-3ds | 404 | Cobrança não encontrada ou não está aguardando autenticação | A cobrança não está em authentication_required ou é de outra conta | Consultar a cobrança antes de retomar |
POST /v1/charges/{id}/resume-3ds | 422 | Dados do cartão não encontrados. Crie uma nova cobrança. | Os dados do cartão não estão mais disponíveis | Criar uma nova cobrança |
POST /v1/charges/{id}/resume-3ds | 422 | Dados do cartão expiraram. Crie uma nova cobrança. | Passaram os 15 minutos de guarda dos dados do cartão | Criar uma nova cobrança |
POST /v1/charges/{id}/resume-3ds | 422 | Dados de autenticação expiraram. Crie uma nova cobrança. | A autenticação terminou depois do prazo | Criar uma nova cobrança. A anterior não é processada |
Planos de assinatura
Todas as rotas de planos respondem403 com Acesso negado para chaves de Desenvolvedor e Financeiro. O Visualizador só acessa as consultas (GET).
| Rota | HTTP | Mensagem | Causa | Ação |
|---|---|---|---|---|
POST /v1/subscription-plans | 400 | Invalid payment methods: ... | Método desconhecido em paymentMethods | Usar só os métodos aceitos |
POST /v1/subscription-plans | 404 | Merchant not found | O merchantId do corpo não é de uma conta a que a chave tem acesso | Conferir o merchantId |
POST /v1/subscription-plans | 404 | Currency not found | Moeda inexistente | Usar BRL |
GET /v1/subscription-plans/{id} | 404 | Subscription plan not found | id inexistente | Conferir o id |
PUT /v1/subscription-plans/{id} | 404 | Subscription plan not found | id inexistente | Conferir o id |
POST /v1/subscription-plans/{id}/image | 404 | Subscription plan not found | id inexistente | Conferir o id |
PATCH /v1/subscription-plans/{id}/status | 404 | Subscription plan not found | id inexistente | Conferir o id |
PATCH /v1/subscription-plans/{id}/status/confirm | 400 | Invalid or expired confirmation token | Token errado, vencido (vale 5 minutos) ou substituído por um pedido de desativação mais novo | Pedir a desativação de novo e confirmar dentro do prazo |
PATCH /v1/subscription-plans/{id}/status/confirm | 404 | Subscription plan not found | Plano inexistente ou de outra conta | Conferir o id |
Assinaturas
Todas as rotas de assinaturas respondem403 com Acesso negado para chaves de Desenvolvedor e Financeiro. O Visualizador só acessa as consultas (GET).
| Rota | HTTP | Mensagem ou código | Causa | Ação |
|---|---|---|---|---|
POST /v1/subscriptions | 400 | Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador | O cartão vai em paymentMethod e o cliente não tem e-mail ou CPF/CNPJ. Vale o documento do cliente já cadastrado com o mesmo e-mail | Usar um cliente com e-mail e CPF ou CNPJ |
POST /v1/subscriptions | 400 | Failed to create subscription | Dados inválidos ou falha na criação | Conferir o corpo, o cartão e o cliente |
POST /v1/subscriptions | 404 | Subscription plan not found or inactive | Plano inexistente ou com status inactive | Conferir o subscriptionPlanId e o status do plano |
POST /v1/subscriptions | 422 | CARD_VALIDATION_FAILED, com message Não foi possível validar o cartão: <motivo> | Plano com trial grátis: a validação de R$ 1,00 foi recusada, ficou em análise ou não teve resposta. Nada é criado | Pedir outro cartão. A message pode ser exibida ao comprador |
POST /v1/subscriptions | 409 | CARD_VALIDATION_IN_PROGRESS | Já há uma validação do mesmo cartão em andamento (requisição repetida em paralelo) | Aguardar a primeira terminar |
POST /v1/subscriptions | 429 | CARD_VALIDATION_RATE_LIMITED | 3 recusas do mesmo cartão em 24 horas, ou 30 recusas na mesma conta em 1 hora | Aguardar e pedir outro cartão |
GET /v1/subscriptions/{id} | 404 | Subscription not found | id inexistente | Conferir o id |
PATCH /v1/subscriptions/{id} | 400 | Only active subscriptions can be updated | A assinatura não está active (inclusive pending_activation) | Atualizar só assinaturas ativas |
PATCH /v1/subscriptions/{id} | 404 | Subscription not found | id inexistente | Conferir o id |
POST /v1/subscriptions/{id}/cancel | 400 | Subscription already cancelled or expired | A assinatura já está cancelled ou expired | Não repetir o cancelamento |
POST /v1/subscriptions/{id}/cancel | 404 | Subscription not found | id inexistente | Conferir o id |
Connect
As rotas do Connect respondem403 com Fast Connect not enabled. quando o módulo não está habilitado na conta master.
Subcontas
| Rota | HTTP | Mensagem | Causa | Ação |
|---|---|---|---|---|
POST /v1/submerchants | 400 | Lista em message, ex.: ["bankAccount.bankCode should not be empty"] ou ["address.country must be a valid ISO31661 Alpha3 code"] | Campo obrigatório ausente ou inválido. Com país BRA, CNPJ, UF, CEP e bairro também são validados | Corrigir os campos indicados. País em 3 letras (BRA) |
POST /v1/submerchants | 400 | Email already registered | canAccessDashboard é true e o e-mail do usuário do painel já existe | Usar outro e-mail para o usuário |
POST /v1/submerchants | 409 | Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco. | O CNPJ já existe entre as subcontas da mesma master (em qualquer status) ou é o CNPJ da própria master | Consultar a subconta existente com GET /v1/submerchants?search= |
POST /v1/submerchants | 500 | Internal server error | Erro interno | Listar as subcontas antes de repetir |
GET /v1/submerchants | 400 | Lista em message | Valor de status fora dos 7 aceitos | Usar active, inactive, pending, pre_approved, correcting, rejected ou blocked |
GET /v1/submerchants | 500 | Internal server error | orderBy com nomes em camelCase (ex.: legalName,-createdAt) | Usar snake_case: legal_name,-created_at |
GET /v1/submerchants/{id}/api-keys | 404 | API keys not found for this submerchant. | A API não encontrou chaves para a subconta | Conferir o id e o status da subconta |
Documentos e representantes
| Rota | HTTP | Mensagem ou código | Causa | Ação |
|---|---|---|---|---|
POST /v1/submerchants/{id}/document | 400 | Validation failed (current file type is text/plain, expected type is ...) | Tipo de arquivo não aceito | Enviar PDF ou imagem (JPG, PNG, GIF, BMP ou WebP) |
POST /v1/submerchants/{id}/document | 400 | File is required | Nenhum arquivo enviado | Enviar o arquivo em multipart/form-data |
POST /v1/submerchants/{id}/document | 400 | Mensagem padrão de validação | Arquivo acima de 50 MB | Reduzir o arquivo |
POST /v1/submerchants/{id}/document | 400 | Invalid document name | Nome de campo fora da lista de documentos | Usar um dos seis nomes aceitos: social_contract, cnpj_card, responsible_document_front, responsible_document_back, selfie_with_document ou irs_letter |
POST /v1/submerchants/{id}/document | 400 | Bad Request | A subconta não pertence à conta master | Conferir o id |
POST /v1/submerchants/{id}/document | 422 | Unprocessable Entity (corpo { "statusCode": 422, "message": "Unprocessable Entity" }) | Subconta já aprovada: os documentos não podem mais ser alterados | Falar com o suporte |
POST /v1/submerchants/{merchantId}/document/upload-token | 404 | Representante legal não encontrado | O legalRepresentativeId não pertence à subconta | Usar um id devolvido em legalRepresentatives ou na listagem de representantes |
POST /v1/document-uploads | 401 | Sem token, ou Token de upload inválido ou expirado | Token ausente, com assinatura inválida ou vencido (300 segundos) | Emitir um novo token e enviar logo em seguida |
POST /v1/document-uploads | 403 | Token de upload expirado ou já utilizado | Token de uso único já usado | Emitir um novo token |
POST /v1/document-uploads | 413 | FILE_TOO_LARGE: O arquivo excede o tamanho máximo de 50 MB. | Arquivo acima de 50 MB. details traz maxMb e actualMb | Reduzir o arquivo |
POST /v1/document-uploads | 415 | UNSUPPORTED_FILE_TYPE: Tipo de arquivo não suportado. Envie PDF ou imagem (JPG, PNG, GIF, BMP ou WebP). | Tipo não aceito. details traz allowed e actualType | Enviar PDF ou imagem aceita |
POST /v1/document-uploads | 400 | NO_FILE_SENT: Nenhum arquivo foi enviado. | Nenhum arquivo no multipart/form-data | Enviar o arquivo, com o nome do documento como nome do campo |
POST /v1/document-uploads | 400 | INVALID_DOCUMENT_NAME: Tipo de documento inválido para este envio. | Nome de campo fora da lista | Usar um dos nomes de documento aceitos |
POST /v1/document-uploads | 422 | DOCUMENT_NOT_EDITABLE: Este documento não pode mais ser alterado no cadastro atual. | Subconta já aprovada | Falar com o suporte |
GET /v1/submerchants/{merchantId}/legal-representatives | 400 | Lista em message | include com valor diferente de documents | Enviar include=documents ou omitir |
GET /v1/submerchants/{merchantId}/legal-representatives | 404 | Merchant não encontrado | A subconta não pertence à conta master autenticada | Conferir o merchantId |
POST /v1/document-uploads, os erros de arquivo vêm no formato { "error": "<CÓDIGO>", "message": "...", "details": { ... } }, sem statusCode. Os erros do token (401 e 403) vêm no formato padrão.
Taxas e dados da subconta
| Rota | HTTP | Mensagem | Causa | Ação |
|---|---|---|---|---|
GET /v1/fast-connect/sub-accounts/{id}/fees-info | 401 | Não autorizado | Credencial inválida | Ver erros comuns |
GET /v1/fast-connect/sub-accounts/{id}/fees-info | 403 | Fast Connect não habilitado para esta conta | Connect não habilitado na conta master | Pedir a habilitação do Connect |
GET /v1/fast-connect/sub-accounts/{id}/fees-info | 404 | Subconta não encontrada | id não vinculado à conta master, inexistente, ou o próprio id da conta master | Usar o id de uma subconta vinculada |
Endpoints de webhook
| Rota | HTTP | Mensagem | Causa | Ação |
|---|---|---|---|---|
POST e PUT /v1/webhook-endpoints | 400 | URL inválida: informe um endereço http(s) público (endereços internos e reservados não são permitidos) | URL interna, reservada ou mal formada. Na validação do corpo, chega em lista em message | Usar um endereço público |
POST e PUT /v1/webhook-endpoints | 400 | Este endereço é reservado e não pode ser usado como destino. | Endereço reservado da plataforma | Usar outro endereço |
POST e PUT /v1/webhook-endpoints | 400 | Apenas contas master com FastConnect habilitado podem receber eventos das subcontas | include_submerchants em conta sem Connect | Retirar include_submerchants |
POST e PUT /v1/webhook-endpoints | 400 | Lista em message | Corpo inválido, como enabled_events que não é lista | Corrigir o corpo |
POST /v1/webhook-endpoints | 403 | Apenas administradores do gateway podem configurar endpoints de nível gateway | Chamada sem merchantId na query | Enviar ?merchantId= com o id da conta |
| Todas | 403 | Acesso negado | Conta sem acesso ao merchantId, ou perfil sem permissão de webhooks | Conferir o merchantId e o perfil de quem gerou a chave |
| Todas | 404 | Merchant não encontrado | merchantId inexistente | Conferir o merchantId |
PUT e DELETE /v1/webhook-endpoints/{webhookId} | 404 | Webhook não encontrado | webhookId inexistente | Conferir o id na listagem |
Veja também
Erros e como tratar
Formato das respostas e quando repetir.
Mapa da API
Todas as rotas e sua autenticação.
Status de cobrança
Recusas, bloqueios e disputas.
Credenciais e ambientes
Permissões da chave e autenticação.

