Documentação da API

Integre pagamentos na sua aplicação de forma simples e segura.

Autenticação

Todos os pedidos à API devem ser autenticados usando a sua API Key. A chave deve ser enviada no cabeçalho (header) Authorization.

Você pode encontrar a sua API Key na sua página de perfil.

Authorization: ApiKey <SUA_API_KEY>

Processar um Pagamento

Para iniciar um novo pagamento, envie uma requisição POST para o seguinte endpoint:

POST /api/v1/processar/

Parâmetros do Corpo (Body)

Parâmetro	Tipo	Obrigatório	Descrição
metodo	string	Sim	O método de pagamento. Atualmente, apenas `"mpesa"` é suportado.
valor	string	Sim	O montante a ser cobrado. Ex: `"150.00"`.
numero_celular	string	Sim	O número de telemóvel do cliente a ser cobrado (ex: `"841234567"`).
referencia_externa	string	Não	Uma referência do seu sistema (ex: ID do pedido).

Exemplos de Requisição

import requests
import json

API_KEY = 'sua_api_key_aqui'
API_URL = 'https://paymoz.tech/api/v1/processar/'

headers = {
    'Authorization': f'ApiKey {API_KEY}',
    'Content-Type': 'application/json'
}

payload = {
    "metodo": "mpesa",
    "valor": "10.00",
    "numero_celular": "841234567"
}

response = requests.post(API_URL, headers=headers, data=json.dumps(payload))

print(response.status_code)
print(response.json())

const apiKey = 'sua_api_key_aqui';
const apiUrl = 'https://paymoz.tech/api/v1/processar/';

const headers = {
    'Authorization': `ApiKey ${apiKey}`,
    'Content-Type': 'application/json'
};

const payload = {
    "metodo": "mpesa",
    "valor": "10.00",
    "numero_celular": "841234567"
};

fetch(apiUrl, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Erro:', error));

curl -X POST https://paymoz.tech/api/v1/processar/ \
  -H "Authorization: ApiKey sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "metodo": "mpesa",
    "valor": "10.00",
    "numero_celular": "841234567"
  }'

Resposta de Sucesso

Quando um pedido de pagamento é processado com sucesso, a API retornará um código de status 200 OK e um corpo JSON com os detalhes da transação.

{
  "sucesso": true,
  "mensagem": "Pagamento processado com sucesso.",
  "dados": {
    "output_ResponseCode": "INS-0",
    "output_ResponseDesc": "Request processed successfully",
    "output_TransactionID": "7m2swkzme9y9",
    "output_ConversationID": "8afbf904889f4e88a35e22ae7df796a7",
    "output_ThirdPartyReference": "PAYMOZOAXCGF"
  }
}

output_TransactionID: O ID único da transação gerado pelo M-Pesa.
output_ConversationID: Um ID de conversação para fins de reconciliação.
output_ThirdPartyReference: A referência única que a Paymoz enviou para o M-Pesa (a mesma que a sua referencia_paymoz).

Respostas de Erro

A API utiliza códigos de status HTTP padrão para indicar o sucesso ou a falha de uma requisição. Em caso de erro, o corpo da resposta conterá um objeto JSON com uma chave erro descrevendo o problema.

400 Bad Request - Requisição Inválida

Ocorre quando faltam parâmetros obrigatórios ou os dados enviados são inválidos.

{
  "erro": "Os campos metodo, valor e numero_celular são obrigatórios."
}

Também pode ocorrer em caso de falha de comunicação com o provedor de pagamento (ex: timeout).

{
  "sucesso": false,
  "erro": "Falha na comunicação com o M-Pesa (Erro 408)."
}

401 Unauthorized - Autenticação Falhou

Ocorre quando a API Key não é fornecida ou é inválida.

{
  "detail": "API Key inválida ou não encontrada."
}

403 Forbidden - Permissão Negada

Ocorre se o utilizador autenticado não tiver permissão para realizar a ação (ex: plano expirado).

{
  "detail": "Você não tem permissão para realizar esta ação."
}

500 Internal Server Error - Erro no Servidor

Indica um erro inesperado no nosso lado. A nossa equipe é notificada automaticamente, mas se o problema persistir, por favor, entre em contacto com o suporte.

{
  "erro": "Ocorreu um erro interno inesperado."
}