Skip to main content

​
Visão Geral

A API EconPay usa códigos de status HTTP padrão para indicar sucesso ou falha de uma requisição.

​
Códigos de Status HTTP

CódigoSignificadoDescrição
200OKRequisição bem-sucedida
400Bad RequestDados inválidos ou faltando
401UnauthorizedToken JWT inválido ou expirado
403ForbiddenSem permissão para acessar o recurso
404Not FoundRecurso não encontrado
500Internal Server ErrorErro interno do servidor

​
Estrutura de Erro

Quando ocorre um erro, a API retorna um JSON com detalhes: 
{
  "success": false,
  "message": "Descrição do erro",
  "error": "Detalhes técnicos do erro"
}

​
Erros Comuns

​
Autenticação

Causa: O token JWT não é válido ou expirou (1 hora de validade)Solução:
// Faça login novamente para obter um novo token
const response = await fetch('https://api.econpay.com.br/auth', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'sua-senha'
  })
});
Causa: O access_token fornecido não existe ou está incorretoSolução:
  • Verifique o access_token no dashboard
  • Certifique-se de usar o token correto (produção vs sandbox)
  • Regenere o token se necessário
Causa: O usuário não tem permissão para executar a açãoSolução:
  • Verifique as permissões do usuário no dashboard
  • Entre em contato com o administrador da conta

​
Pagamentos

Causa: Campos obrigatórios faltando ou formato incorretoExemplo de erro:
{
  "success": false,
  "message": "Dados de pagamento inválidos",
  "error": "Campo 'customer.email' é obrigatório"
}
Solução:
  • Verifique todos os campos obrigatórios
  • Valide formatos (email, CPF, telefone)
  • Consulte a documentação do endpoint
Causa: Tentou criar pagamento com cartão sem enviar dados do cartãoSolução:
{
  "payment": {
    "type": "credit",
    "installments": 3,
    "credit_card": {
      "number": "4000000000000010",
      "holder_name": "NOME NO CARTAO",
      "exp_month": 12,
      "exp_year": 2025,
      "cvv": "123"
    }
  }
}
Causa: O valor da transação é menor que R$ 5,00Exemplo de erro:
{
  "success": false,
  "message": "Valor mínimo não atingido",
  "error": "O valor mínimo para transações é R$ 5,00. Valor enviado: R$ 2,00"
}
Solução:
  • Certifique-se de que o valor total é >= 500 centavos (R$ 5,00)
Causa: Data de expiração do cartão em formato incorretoSolução:
{
  "credit_card": {
    "exp_month": 12,    // Número de 1 a 12
    "exp_year": 2025    // Ano completo (YYYY)
  }
}

​
Transações

Causa: O ID da transação não existe ou não pertence à sua contaSolução:
  • Verifique se o ID está correto
  • Certifique-se de que a transação pertence à sua conta
  • Use o endpoint de listagem para encontrar transações
Causa: A transação não está em um status que permite estornoExemplo de erro:
{
  "success": false,
  "message": "Transação não pode ser estornada",
  "error": "Apenas transações com status APPROVED podem ser estornadas. Status atual: PENDING"
}
Solução:
  • Verifique o status da transação
  • Aguarde a aprovação antes de tentar estornar
  • Transações PENDING, FAILED ou REFUNDED não podem ser estornadas

​
Configuração

Causa: Não há configuração de subadquirente para o tipo de pagamentoExemplo de erro:
{
  "success": false,
  "message": "Configuração de roteamento não encontrada",
  "error": "Nenhuma configuração encontrada para company_id: 1 e payment_type: pix"
}
Solução:
  • Configure a subadquirente no dashboard
  • Entre em contato com o suporte
  • Verifique se o método de pagamento está habilitado

​
Erros de Subadquirente

Quando a subadquirente (Firebank, etc) retorna erro: 
{
  "success": false,
  "message": "Erro ao processar pagamento na subadquirente",
  "error": "Cartão recusado pela operadora"
}

​
Erros Comuns de Cartão

ErroCausaSolução
Cartão recusadoSem limite ou bloqueadoCliente deve contatar banco
Cartão expiradoData de validade passouUsar cartão válido
CVV inválidoCVV incorretoVerificar código de segurança
Dados inválidosNúmero ou nome incorretoVerificar dados do cartão

​
Tratamento de Erros

​
Exemplo em JavaScript

async function createPayment(paymentData) {
  try {
    const response = await fetch('https://api.econpay.com.br/payments/order', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(paymentData)
    });
    
    const data = await response.json();
    
    if (!response.ok) {
      // Tratar erro baseado no status
      switch (response.status) {
        case 400:
          console.error('Dados inválidos:', data.error);
          break;
        case 401:
          console.error('Token expirado, fazendo login novamente...');
          await refreshToken();
          break;
        case 403:
          console.error('Sem permissão:', data.error);
          break;
        case 404:
          console.error('Recurso não encontrado:', data.error);
          break;
        case 500:
          console.error('Erro no servidor:', data.error);
          break;
        default:
          console.error('Erro desconhecido:', data.error);
      }
      
      throw new Error(data.message);
    }
    
    return data;
  } catch (error) {
    console.error('Erro ao criar pagamento:', error);
    throw error;
  }
}

​
Exemplo em Python

import requests

def create_payment(payment_data, token):
    try:
        response = requests.post(
            'https://api.econpay.com.br/payments/order',
            headers={
                'Authorization': f'Bearer {token}',
                'Content-Type': 'application/json'
            },
            json=payment_data
        )
        
        data = response.json()
        
        if not response.ok:
            # Tratar erro baseado no status
            if response.status_code == 400:
                print(f'Dados inválidos: {data["error"]}')
            elif response.status_code == 401:
                print('Token expirado, fazendo login novamente...')
                refresh_token()
            elif response.status_code == 403:
                print(f'Sem permissão: {data["error"]}')
            elif response.status_code == 404:
                print(f'Recurso não encontrado: {data["error"]}')
            elif response.status_code == 500:
                print(f'Erro no servidor: {data["error"]}')
            
            raise Exception(data['message'])
        
        return data
    except requests.exceptions.RequestException as e:
        print(f'Erro ao criar pagamento: {e}')
        raise

​
Retry Logic

Para erros temporários (500, timeout), implemente retry com backoff exponencial: 
async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      // Apenas retry em erros 500 ou timeout
      if (error.status !== 500 && error.code !== 'ETIMEDOUT') {
        throw error;
      }
      
      // Backoff exponencial: 1s, 2s, 4s
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

// Uso
const payment = await retryRequest(() => createPayment(paymentData));

​
Suporte

Se você encontrar um erro não documentado ou precisar de ajuda:

Contate o Suporte

Nossa equipe está pronta para ajudar