Documentação da API

Integre o Maxymus Pay ao seu sistema de forma simples e rápida

Navegação

Base URL https://maxymuspay.com/api/v1

Introdução

A API do Maxymus Pay 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
  • Proteção contra duplicidade (Idempotency-Key)

Headers Obrigatórios

Todas as requisições de criação (POST) exigem os seguintes headers:

Header Obrigatório Descrição
Authorization Sim Bearer token de autenticação
X-Client-ID Sim Identificador público da credencial
Idempotency-Key Sim Chave única por requisição (12-128 caracteres). Use um UUID v4 ou string aleatória. Evita cobranças duplicadas em caso de retry. Válida por 30 minutos.
Content-Type Sim application/json

⚠️ Se o Idempotency-Key não for enviado ou tiver menos de 12 caracteres, a API retornará erro 422. Se a mesma chave for reutilizada dentro de 30 minutos, retornará erro 409.

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://maxymuspay.com/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

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://maxymuspay.com/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"
  }
}

Cashin - Depósitos via PIX

Crie depósitos via PIX para adicionar saldo à conta do usuário autenticado.

Endpoint

POST https://maxymuspay.com/api/v1/cashin/pix

Parâmetros

Campo Tipo Obrigatório Descrição
amount float Sim Valor do depósito (mínimo: R$ 1,00)
payer_name string Não Nome do pagador (usa o nome da conta se não informado)

Resposta de Sucesso (200)

{
  "success": true,
  "transaction": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "beb1631e-8206-4c66-9cf4-775fb9d57bf0",
    "amount_gross": 10.00,
    "amount_net": 7.80,
    "fee": 2.20,
    "status": "pending",
    "expires_at": "2026-03-28T16:03:34-03:00"
  },
  "qr_code": "00020101021226940014br.gov.bcb.pix...",
  "qr_code_image_url": "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=..."
}

Consultar Transações

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

Listar Transações

GET https://maxymuspay.com/api/v1/transactions

Buscar Transação por UUID

GET https://maxymuspay.com/api/v1/transactions/{uuid}

Parâmetros (Query String)

Campo Tipo Descrição
status string Filtrar por status (completed, pending, failed)
type string Filtrar por tipo (pix, credit)
start_date date Data inicial (ex: 2026-01-01)
end_date date Data final (ex: 2026-12-31)
page integer Número da página
per_page integer Itens por página (padrão: 20)

Webhooks (Notificações)

Receba notificações automáticas em seu sistema sempre que o status de uma transação mudar.

Configuração

Configure a URL de callback (Webhook) na página "Chave API" do painel, no campo "URL de Webhook" da sua credencial. O sistema enviará notificações automáticas para essa URL sempre que uma transação mudar de status.

Eventos Disparados

Evento Descrição
transaction.completed Disparado quando uma transação (PIX ou Cartão) é confirmada como paga.
deposit.completed Disparado quando um depósito PIX é confirmado e creditado.
withdrawal.completed Disparado quando um saque PIX é processado com sucesso.

Exemplo de Payload (JSON)

O sistema enviará uma requisição POST para sua URL com o seguinte corpo:

{
  "event": "transaction.completed",
  "created_at": "2026-03-28T12:30:00Z",
  "data": {
    "transaction_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "amount_gross": 100.00,
    "amount_net": 97.80,
    "fee": 2.20,
    "type": "pix",
    "gateway_provider": "pluggou",
    "external_id": "beb1631e-8206-4c66-9cf4-775fb9d57bf0",
    "created_at": "2026-03-28T12:25:00Z"
  }
}

Verificação de Assinatura

Cada webhook inclui o header X-Webhook-Signature com uma assinatura HMAC-SHA256 do payload, usando seu Token (Secret) como chave. Valide a assinatura para garantir que a requisição é legítima. 

// Exemplo de validação em PHP
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $payload, 'SEU_TOKEN_SECRET');

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Assinatura inválida');
}

Resposta Esperada

Seu servidor deve responder com status HTTP 200 OK para confirmar o recebimento. Caso contrário, o sistema tentará reenviar a notificação automaticamente (até 3 tentativas com intervalo de 60 segundos).

Exemplo em PHP

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

PHP 
<?php

$client = new \GuzzleHttp\Client();

$idempotencyKey = bin2hex(random_bytes(16)); // Gera chave única

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

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

Exemplo em Python

Exemplo usando a biblioteca requests.

Python 
import requests
import uuid

url = "https://maxymuspay.com/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"
}

headers = {
    "Authorization": "Bearer SEU_TOKEN",
    "X-Client-ID": "SEU_CLIENT_ID",
    "Idempotency-Key": str(uuid.uuid4()),  # Chave única por requisição
    "Content-Type": "application/json"
}

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

print(response.json())

Exemplo em JavaScript

Exemplo usando fetch API.

JavaScript 
const url = "https://maxymuspay.com/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"
};

const headers = {
    "Authorization": "Bearer SEU_TOKEN",
    "X-Client-ID": "SEU_CLIENT_ID",
    "Idempotency-Key": crypto.randomUUID(), // Chave única por requisição
    "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 
curl -X POST "https://maxymuspay.com/api/v1/payments/pix" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Client-ID: SEU_CLIENT_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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"
  }'

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).
409 Conflict Requisição duplicada. O Idempotency-Key já foi utilizado nos últimos 30 minutos.
422 Unprocessable Entity Erro de validação (ex: email inválido, Idempotency-Key ausente ou inválido).
500 Internal Server Error Erro interno do servidor. Tente novamente mais tarde.