Documentação da API

Introdução

A API do MonezPay permite que você integre pagamentos PIX e Cartão de Crédito ao seu sistema de forma simples e segura.

Características

API RESTful completa
Autenticação via Token Bearer
Webhooks em tempo real
Respostas em JSON

Obter Credenciais de API

Para usar a API, você precisa gerar uma chave de API no painel do sistema.

Passo 1: Acesse a página de Chaves de API

No painel do sistema, acesse a seção "Chave API" no menu lateral.

Ir para Chaves de API →

Passo 2: Gere uma nova chave

Clique em "Gerar Nova Chave" e dê um nome descritivo (ex: "Site Principal", "App Mobile").

⚠️ Importante: Copie e guarde o token imediatamente, pois ele só será exibido uma vez!

Passo 3: Configure no seu sistema

Adicione o token gerado nas configurações do seu site/aplicação. O token terá o formato:

nxp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Integração PIX

Crie pagamentos PIX e receba notificações em tempo real quando o pagamento for confirmado.

Endpoint

POST https://moonezpay.site/api/v1/payments/pix

Parâmetros

Campo	Tipo	Obrigatório	Descrição
amount	float	Sim	Valor do pagamento (mínimo: R$ 0,01)
payer_name	string	Sim	Nome completo do pagador
payer_email	string	Sim	Email do pagador
payer_cpf	string	Sim	CPF do pagador (apenas números)
description	string	Não	Descrição do pagamento
webhook_url	string (URL)	Sim	URL para receber o webhook específico deste pagamento

Resposta de Sucesso (201)

{
  "success": true,
  "data": {
    "transaction_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 100.00,
    "fee": 4.00,
    "amount_net": 96.00,
    "status": "pending",
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "pix_code": "00020126580014BR.GOV.BCB.PIX...",
    "pix_key": "00020126580014BR.GOV.BCB.PIX...",
    "expires_at": "2024-11-26T12:30:00Z",
    "expires_in_seconds": 300
  }
}

Cashout - Saques via PIX

Crie saques via PIX para transferir saldo da conta do usuário para uma chave PIX.

Importante: Para saques automáticos funcionarem, você precisa: 1. Configurar o modo de saque como "Automático" ao criar a credencial de API 2. Adicionar o IP do seu servidor nas configurações da API 3. O usuário precisa estar aprovado (KYC) e com saques desbloqueados

Endpoint

POST https://moonezpay.site/api/v1/cashout/pix

Parâmetros

Campo	Tipo	Obrigatório	Descrição
amount	float	Sim	Valor líquido desejado (mínimo: R$ 10,00). O sistema calcula automaticamente o valor bruto incluindo taxas.
pix_key	string	Sim	Chave PIX de destino (CPF, Email, Telefone ou Chave Aleatória)

Resposta de Sucesso

{
  "success": true,
  "message": "Saque criado e processado automaticamente.",
  "withdrawal": {
    "id": 123,
    "amount": 95.00,
    "amount_gross": 100.00,
    "fee": 5.00,
    "status": "processing",
    "pix_key": "12345678900"
  }
}

Consultar Transações

Liste e filtre as transações da sua conta ou busque uma transação específica.

Listar Transações

GET https://moonezpay.site/api/v1/transactions

Parâmetros (Query String)

Campo	Tipo	Descrição
status	string	Filtrar por status (paid, pending, failed, etc)
page	integer	Número da página
limit	integer	Itens por página (padrão: 15)

Webhooks (Notificações)

Webhook é a forma recomendada de receber a confirmação do pagamento (pago / pendente / falhou) em tempo real, sem precisar ficar consultando o status.

Como configurar

A configuração do webhook é feita diretamente na criação da transação.
Envie o parâmetro webhook_url no payload de criação da transação.

Exemplo: https://seusite.com/webhooks/webhook

⚠️ O webhook é enviado para todas as suas chaves ativas que tenham Webhook URL configurada.

Assinatura (Segurança)

Para garantir que a notificação foi enviada pelo MonezPay, nós assinamos o payload com HMAC SHA-256 e enviamos no header:

X-Webhook-Signature: <HMAC_SHA256>

A chave usada na assinatura é o seu token de API (o mesmo usado no Authorization Bearer).

<?php
// Exemplo de validação do Webhook (PHP)
$raw = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$token = 'SEU_TOKEN_DE_API_AQUI';
$expected = hash_hmac('sha256', $raw, $token);

if (!hash_equals($expected, $received)) {
  http_response_code(401);
  echo 'invalid signature';
  exit;
}

$payload = json_decode($raw, true);
// Processe o evento...
http_response_code(200);
echo 'ok';

Eventos disparados

Evento	Quando acontece
transaction.waiting_payment	Cobrança criada / aguardando pagamento.
transaction.completed	Pagamento confirmado (pago).
deposit.completed	Evento adicional para depósito PIX confirmado.
transaction.failed	Falha/expiração/cancelamento da transação.
withdrawal.completed	Saque concluído (quando você usa o cashout).

Exemplo de payload (JSON)

O MonezPay envia uma requisição POST para sua Webhook URL com o corpo abaixo:

{
  "event": "transaction.completed",
  "created_at": "2026-02-25T04:19:10Z",
  "data": {
    "id": 123,
    "uuid": "0b55f102-2cbd-450f-b65f-4e5af080fc0f",
    "external_id": "0b55f102-2cbd-450f-b65f-4e5af080fc0f",
    "type": "pix",
    "status": "completed",
    "gateway_provider": "misticpay",
    "amount_gross": 20.00,
    "fee": 2.10,
    "amount_net": 17.90,
    "payer_name": "Renato Gomes",
    "payer_email": "renato@email.com",
    "payer_cpf": "12345678900",
    "expires_at": "2026-02-25T04:23:28Z",
    "created_at": "2026-02-25T04:18:29Z",
    "updated_at": "2026-02-25T04:19:10Z"
  }
}

✅ No seu sistema, o ideal é usar uuid (ou external_id) como chave para identificar o pedido do seu cliente e liberar o produto/serviço quando chegar transaction.completed.

Resposta esperada

Seu endpoint deve responder com HTTP 200 OK. Se retornar 5xx ou der timeout, o sistema tentará reenviar automaticamente.

Exemplo em PHP

Exemplo de criação de pagamento PIX usando Guzzle.

<?php

$client = new \GuzzleHttp\Client();

$response = $client->post('https://moonezpay.site/api/v1/payments/pix', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'X-Client-ID' => 'SEU_CLIENT_ID',
        'Accept' => 'application/json',
    ],
    'json' => [
        'amount' => 100.00,
        'payer_name' => 'João Silva',
        'payer_email' => 'joao@email.com',
        'payer_cpf' => '12345678900',
        'description' => 'Pagamento de Teste',
        'webhook_url' => 'https://seu-sistema.com/api/webhook'
    ]
]);

$body = json_decode($response->getBody(), true);
print_r($body);

Exemplo em Python

Exemplo usando a biblioteca requests.

import requests

url = "https://moonezpay.site/api/v1/payments/pix"

payload = {
    "amount": 100.00,
    "payer_name": "João Silva",
    "payer_email": "joao@email.com",
    "payer_cpf": "12345678900",
    "description": "Pagamento de Teste",
    "webhook_url": "https://seu-sistema.com/api/webhook"
}

headers = {
    "Authorization": "Bearer SEU_TOKEN",
    "X-Client-ID": "SEU_CLIENT_ID",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Exemplo em JavaScript

Exemplo usando fetch API.

const url = "https://moonezpay.site/api/v1/payments/pix";

const payload = {
    amount: 100.00,
    payer_name: "João Silva",
    payer_email: "joao@email.com",
    payer_cpf: "12345678900",
    description: "Pagamento de Teste",
    webhook_url: "https://seu-sistema.com/api/webhook"
};

const headers = {
    "Authorization": "Bearer SEU_TOKEN",
    "X-Client-ID": "SEU_CLIENT_ID",
    "Content-Type": "application/json"
};

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

Exemplo cURL

curl -X POST "https://moonezpay.site/api/v1/payments/pix" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Client-ID: SEU_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "payer_name": "João Silva",
    "payer_email": "joao@email.com",
    "payer_cpf": "12345678900",
    "description": "Pagamento de Teste",
    "webhook_url": "https://seu-sistema.com/api/webhook"
  }'

Códigos de Erro

Lista de possíveis códigos de status HTTP retornados pela API.

Código	Significado	Descrição
200	OK	Requisição processada com sucesso.
201	Created	Recurso criado com sucesso (ex: novo pagamento).
400	Bad Request	Dados inválidos enviados na requisição. Verifique os campos.
401	Unauthorized	Token inválido ou não fornecido.
403	Forbidden	Acesso negado ao recurso solicitado.
404	Not Found	Recurso não encontrado (ex: transação inexistente).
422	Unprocessable Entity	Erro de validação (ex: email inválido, saldo insuficiente).
500	Internal Server Error	Erro interno do servidor. Tente novamente mais tarde.

Documentação da API

Navegação

Introdução

Características

Obter Credenciais de API

Passo 1: Acesse a página de Chaves de API

Passo 2: Gere uma nova chave

Passo 3: Configure no seu sistema

Integração PIX

Endpoint

Parâmetros

Resposta de Sucesso (201)

Cashout - Saques via PIX

Endpoint

Parâmetros

Resposta de Sucesso

Consultar Transações

Listar Transações

Parâmetros (Query String)

Webhooks (Notificações)

Como configurar

Assinatura (Segurança)

Eventos disparados

Exemplo de payload (JSON)

Resposta esperada

Exemplo em PHP

Exemplo em Python

Exemplo em JavaScript

Exemplo cURL

Códigos de Erro