Códigos de Erro & Diagnóstico

A EDPay unifica as respostas de múltiplos canais de pagamento num padrão estruturado com prefixo EDP-. O integrador recebe códigos unificados, mensagens claras e diagnóstico técnico acionável.

Arquitetura do Padrão Unificado EDPay

Ao integrar com a EDPay, a sua aplicação deixa de lidar com especificidades desconexas e respostas divergentes de diferentes provedores. O motor da EDPay normaliza os erros de múltiplos canais para o padrão unificado EDP-xxx, acompanhado do código HTTP correspondente, ação recomendada para resolução e detalhes técnicos de diagnóstico.

Resposta de Erro Unificada (Ex: Saldo Insuficiente)

HTTP 422 Unprocessable Entity

{
  "status": "failed",
  "code": "EPP-2006",
  "message": "Insufficient customer balance to complete payment transaction.",
  "channel": "mobile_wallet",
  "details": {
    "error_code": "EPP-2006",
    "description": "Customer mobile money or card balance is insufficient for requested amount.",
    "conversation_id": "AG_20261107_00005e7dccc6da08efa8",
    "reference": "T12344C",
    "action_required": "Prompt the customer to top up funds or select an alternate payment method."
  }
}

Resposta de Sucesso Unificada (EDP-0)

HTTP 200 OK

{
  "status": "success",
  "code": "EPP-0",
  "message": "Payment authorized and transaction processed successfully.",
  "data": {
    "transaction_id": "EDP_TX_94827104",
    "conversation_id": "AG_20261107_00005e7dccc6da08efa8",
    "channel": "mobile_wallet",
    "amount": "100.00",
    "currency": "MZN",
    "customer_phone": "25884xxxxxxx",
    "reference": "053B3M"
  }
}

Chamada C2B (Single Stage USSD Push)

Na chamada C2B (Customer-to-Business), os fundos são deduzidos da carteira móvel do cliente e creditados na conta da empresa. O gateway da EDPay despoleta um USSD Push direto no telemóvel do cliente para introdução do PIN de autorização. O PIN nunca é armazenado e serve exclusivamente para autenticar o débito.

Resource Endpoint

Servidor	Método	Endpoint Path	SSL / TLS
api-pay.edutecka.com	POST	/v1/payments/charges	✔ HTTPS (TLS 1.3)

Exemplo de Requisição C2B Unificada

POST /v1/payments/charges HTTP/1.1
Host: api-pay.edutecka.com
Content-Type: application/json
X-EDPay-Public-Key: pk_live_49f81a7b8e2c...
X-EDPay-Private-Key: sk_live_82c13e4a1d9f...
Origin: https://seusite.co.mz

{
  "reference": "T12344C",
  "customer_phone": "25884xxxxxxx",
  "amount": 10.00,
  "currency": "MZN",
  "channel": "mobile_wallet",
  "client_reference": "053B3M"
}

Parâmetros de Requisição & Resposta

Campos aceites pela API e mapeados diretamente para as operadoras móveis parceiras.

Parâmetros de Envio (Request Body)

Parâmetro EDPay	Mapeamento Gateway	Tipo	Obrigatório	Exemplo / Descrição
reference	input_TransactionReference	String	✔	Referência única da encomenda ou fatura (1 a 20 chars). Ex: `T12344C`
customer_phone	input_CustomerMSISDN	String	✔	Número de telemóvel moçambicano (+258). Ex: `25884xxxxxxx`
amount	input_Amount	Decimal / Number	✔	Valor em Meticais a debitar ao cliente. Ex: `10.00`
channel	input_ServiceProviderCode	String	✔	Código do método de pagamento retornado por `GET /v1/public/payment-methods`
client_reference	input_ThirdPartyReference	String	✔	Identificador de rastreamento no sistema terceiro. Ex: `053B3M`

Parâmetros de Retorno (Response Body)

Campo EDPay	Mapeamento Operadora	Tipo	Descrição Técnica
code	output_ResponseCode	String	Código unificado EDPay (ex: `EDP-0`, `EDP-2006`)
message	output_ResponseDesc	String	Mensagem descritiva em português para fácil leitura
conversation_id	output_ConversationID	String	Identificador da sessão gerado pela plataforma da operadora
transaction_id	output_TransactionID	String	ID da transação para consulta e conciliação

Matriz Unificada de Códigos EDPay (44)

Catálogo completo e padronizado de códigos de resposta da EDPay (EDP-xxx) com diagnóstico técnico e ações recomendadas para integração.

Descarregar JSON

Código EDPay	HTTP	Significado & Diagnóstico	Ação Recomendada
EPP-0	200 / 201	Sucesso Transação autorizada e processada com sucesso no canal de pagamento	Concluir o pedido e entregar o serviço ou produto ao cliente.
EPP-1	500	Erro Interno no Processador Falha interna transitória na rede do processador ou operadora	Aguardar alguns instantes e tentar novamente com a mesma chave de idempotência.
EPP-2	401	Chaves de Autenticação Inválidas Chaves X-EDPay-Public-Key ou X-EDPay-Private-Key inválidas, ausentes ou expiradas	Verificar as chaves API (pk_ / sk_) enviadas nos cabeçalhos da requisição.
EPP-4	401	Conta Não Ativa A conta do comerciante ou do cliente não se encontra ativa para transações	Verificar o estado da conta e requisitos de compliance no painel da EDPay.
EPP-5	401	Cancelado pelo Cliente O cliente cancelou o pedido no telemóvel ou o prompt USSD expirou sem confirmação	Notificar o cliente e disponibilizar nova tentativa de pagamento.
EPP-6	401	Falha na Transação Transação rejeitada pelas regras de risco e segurança do canal de pagamento	Solicitar ao cliente a verificação da conta ou utilizar outro método.
EPP-9	408	Timeout na Autorização Tempo limite de espera da confirmação por PIN excedido pela rede	Consultar o estado da cobrança via GET /v1/payments ou aguardar webhook.
EPP-10	409	Transação Duplicada A referência externa já foi utilizada para outra transação concluída	Gerar um identificador de referência único para uma nova cobrança.
EPP-13	400	Código de Serviço Inválido Código de serviço, entidade ou subconta de destino inválido	Verificar as configurações de canal no painel da EDPay.
EPP-14	400	Referência Inválida A referência da transação possui formato ou caracteres não permitidos	Utilizar referências alfanuméricas sem espaços nem símbolos especiais.
EPP-15	400	Montante Inválido O valor solicitado está fora dos limites mínimos ou máximos do canal	Garantir valor numérico decimal válido e dentro dos limites operacionais.
EPP-16	503	Sobrecarga Temporária O gateway ou canal está temporariamente sobrecarregado	Repetir a chamada após um intervalo com retentativas controladas.
EPP-17	400	Comprimento de Referência Inválido O tamanho da referência deve ter entre 1 e 20 caracteres	Ajustar o tamanho da referência da transação para o intervalo de 1 a 20 caracteres.
EPP-18	400	ID de Transação Inválido Identificador da transação inexistente ou formato corrompido	Verificar o ID retornado na chamada inicial de autorização.
EPP-19	400	Referência Externa Inválida A referência do sistema parceiro fornecida é inválida	Enviar um identificador de sistema terceiro válido.
EPP-20	400	Parâmetros Incompletos Campos obrigatórios em falta no payload da requisição	Rever o payload e assegurar que todos os campos obrigatórios estão preenchidos.
EPP-21	400	Validação de Dados Falhou Um ou mais campos não cumpriram a validação de tipo ou schema	Validar a estrutura JSON e tipos numéricos/textuais dos campos.
EPP-22	400	Tipo de Operação Inválido A operação solicitada não é válida para este canal de pagamento	Utilizar operações homologadas para o canal selecionado.
EPP-23	400	Estado Não Conclusivo A operadora ou banco reportou estado indefinido ou não conclusivo	Contactar o suporte técnico EDPay ([email protected]).
EPP-24	400	Iniciador Inválido Identificador de iniciador não reconhecido ou sem permissões	Confirmar credenciais do projeto no painel da EDPay.
EPP-25	400	Credencial de Segurança Inválida Chave ou assinatura de segurança da transação inválida	Atualizar as chaves de integração e certificados da conta.
EPP-26	403	Não Autorizado A conta não possui permissão para executar o método solicitado	Subscrever ou solicitar ativação do método no painel EDPay.
EPP-995	400	Restrição no Perfil do Cliente A conta do cliente no canal emissor possui bloqueios ou irregularidades	O cliente deve contactar o operador emissor para regularizar o perfil.
EPP-996	400	Carteira Inativa A carteira ou conta do cliente encontra-se desativada ou suspensa	Solicitar ao cliente outro número de telemóvel ou método para pagamento.
EPP-997	400	Transação Não Encontrada A transação referenciada para vínculo ou conciliação não existe	Confirmar o ID ou referência da transação original.
EPP-998	400	Mercado Não Suportado País ou operadora fora da área geográfica suportada	Operação restrita a números móveis e contas bancárias moçambicanas.
EPP-2001	401	Autenticação do Iniciador Falhou Falha de autenticação junto do gateway central do provedor	Rever credenciais e permissões de produção da conta EDPay.
EPP-2002	400	Destinatário Inválido Conta ou carteira de destino de liquidação inválida	Confirmar as contas bancárias ou carteiras de liquidação associadas.
EPP-2006	422	Saldo Insuficiente O cliente não possui saldo suficiente para cobrir o valor total da compra	Solicitar ao cliente recarga da conta ou selecionar outro canal.
EPP-2051	400	Número de Contacto Inválido O número de telemóvel ou contacto não cumpre o formato internacional válido	Fornecer número com indicativo internacional válido (ex: 258...) e 9 dígitos.
EPP-2057	400	Código de Idioma Inválido O código de idioma para mensagens não é suportado pelo canal	Utilizar códigos de idioma válidos: PT (Português) ou EN (Inglês).
EPP-3001	402	Recusado pelo Emissor (Do Not Honor) O banco emissor do cartão recusou a cobrança sem especificar motivo detalhado	Solicitar ao titular que contacte o banco emissor do cartão ou use outro cartão.
EPP-3002	400	Cartão Expirado A data de validade indicada no cartão já expirou	Verificar a data de expiração (mês/ano) ou introduzir outro cartão válido.
EPP-3003	400	Número de Cartão Inválido O número do cartão fornecido falhou na validação de algoritmo de Luhn	Confirmar os dígitos do cartão Visa ou Mastercard.
EPP-3004	400	Código CVV / CVC Incorreto O código de segurança de 3 dígitos introduzido não coincide com o registo do cartão	Introduzir o código de 3 dígitos que consta no verso do cartão físico.
EPP-3005	402	Falha na Autenticação 3D Secure O titular do cartão cancelou a validação biométrica/OTP do 3DS ou o tempo limite expirou	Reiniciar o pagamento e assegurar a aprovação na app do banco emissor.
EPP-3006	422	Limite Diário do Cartão Excedido A transação excede o teto máximo diário de compras online estipulado pelo banco	Ajustar o limite temporário na app bancária ou fracionar a compra.
EPP-3007	403	Cartão Bloqueado ou Sinalizado por Fraude O cartão foi sinalizado como perdido, furtado ou restrito na rede de adquirentes	Operação bloqueada preventivamente. Utilizar outro meio de pagamento.
EPP-4001	400	NIB ou IBAN Inválido O Número de Identificação Bancária (NIB) não cumpre o checksum bancário moçambicano (21 dígitos)	Conferir o NIB de 21 dígitos associado à conta bancária de liquidação.
EPP-4002	422	Janela de Compensação Encerrada O pedido de liquidação bancária ocorreu após o horário de corte do sistema interbancário	A compensação financeira será executada no próximo dia útil bancário.
EPP-4003	422	Conta Bancária de Destino Inativa ou Bloqueada A instituição de crédito rejeitou o crédito por encerramento ou bloqueio da conta beneficiária	Atualizar os dados da conta bancária de liquidação no painel da EDPay.
EPP-5001	403	Comprovação Documental de Transação Obrigatória A transação foi retida preventivamente pela equipa de compliance para auditoria de legitimidade	Apresentar fatura, contrato ou comprovativo de entrega no prazo de até 48 horas úteis.
EPP-5002	403	Conta Suspensa para Auditoria AML/CFT Operações bloqueadas preventivamente com base na Lei n.º 11/2019 de combate à lavagem de capitais	Contactar imediatamente o departamento de compliance ([email protected]).
EPP-5003	403	Uso Não Autorizado de Documentos de Terceiros Identificação ou conta pertencente a terceiros sem consentimento formal comprovado	Conta cancelada sem reembolso nos termos das Políticas da EDPay e reportada às autoridades.