MagionPay API v1

Inicio rapido

Base URL: /api/v1
Gere uma API Key no painel: /app/api-keys
Headers para endpoints protegidos: Content-Type: application/json e X-Api-Key: SUA_CHAVE
Idempotencia (opcional): envie X-Idempotency-Key para evitar cobrancas duplicadas.
Rate limit: 60 req/min por API key (HTTP 429 com Retry-After).
GET /api/v1/ping e publico (sem API key).

Autenticacao

Os endpoints de cobranca exigem o header X-Api-Key. O endpoint /ping e publico.

curl -X GET {{BASE_URL}}/ping

Criar uma cobranca

POST/api/v1/charges

Campos principais (JSON):

Campo	Descricao	Obrigatorio
`valor`	Valor em centavos (ex.: 1000 = R$10,00)	Sim
`cliente`	Objeto com `nome`, `email` e `cpf` do pagador	Sim
`moeda`	Padrao `BRL` quando omitido	Nao
`descricao`	Texto livre (ate 255)	Nao
`callback`	URL para callback imediato	Nao
`metodos`	Lista; use `["pix"]`, `["boleto"]` ou `["cartao"]`	Nao

Obs.: se metodos nao for enviado, o sistema usa pix como padrao.

curl -X POST {{BASE_URL}}/charges \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: SUA_CHAVE" \
  -H "X-Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000" \
  -d '{
    "valor": 2500,
    "cliente": {
      "nome": "Maria Souza",
      "email": "maria@email.com",
      "cpf": "12345678900"
    },
    "moeda": "BRL",
    "descricao": "Pedido #123",
    "metodos": ["pix"]
  }'

Resposta (200/201):

{
  "id": 42,
  "status": "pendente",
  "valor": 2500,
  "moeda": "BRL",
  "metodo": "pix",
  "descricao": "Pedido #123",
  "cliente": {
    "nome": "Maria Souza",
    "email": "maria@email.com",
    "cpf": "12345678900"
  },
  "callback_url": null,
  "idempotency": "123e4567-e89b-12d3-a456-426614174000",
  "referencia": "ch_a1b2c3d4",
  "gateway": {
    "qr_code": "00020101021226...6304C116",
    "qr_code_url": "https://api.qrserver.com/v1/create-qr-code/?data=000201...",
    "expira_em": "2025-12-31 23:59:59"
  },
  "criado_em": "2025-12-04 10:00:00",
  "atualizado_em": "2025-12-04 10:00:00"
}

Exemplo em PHP

$body = [
  "valor" => 2500,
  "cliente" => [
    "nome" => "Maria Souza",
    "email" => "maria@email.com",
    "cpf" => "12345678900"
  ],
  "moeda" => "BRL",
  "descricao" => "Pedido #123",
  "metodos" => ["pix"]
];
$ch = curl_init("{{BASE_URL}}/charges");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: SUA_CHAVE",
    "X-Idempotency-Key: ch_".uniqid()
  ],
  CURLOPT_POSTFIELDS => json_encode($body)
]);
$resp = curl_exec($ch);
curl_close($ch);
echo $resp;

Consultar cobranca

GET/api/v1/charges/{id}

curl -X GET {{BASE_URL}}/charges/42 \
  -H "X-Api-Key: SUA_CHAVE"

Resposta: mesma estrutura da criacao (inclui gateway e status atual).

Transferencia / Saque PIX

POST/api/v1/withdrawals

Campos principais (JSON):

Campo	Descricao	Obrigatorio
`valor`	Valor em centavos (ex.: 1000 = R$10,00)	Sim
`pix_chave`	Chave PIX do destinatario	Sim
`pix_tipo`	`cpf`, `cnpj`, `email`, `celular`, `aleatoria`	Sim
`cliente`	Objeto com `nome`, `email` e `cpf` do solicitante	Sim
`descricao`	Texto livre (ate 255)	Nao

Obs.: se transferencia_pix_auto estiver desativado, o saque fica como aguardando_admin.

curl -X POST {{BASE_URL}}/withdrawals \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: SUA_CHAVE" \
  -d '{
    "valor": 1000,
    "pix_chave": "12345678909",
    "pix_tipo": "cpf",
    "descricao": "Saque do cliente",
    "cliente": {
      "nome": "Maria Souza",
      "email": "maria@email.com",
      "cpf": "12345678900"
    }
  }'

Resposta (201):

{
  "id": 91,
  "status": "processando",
  "valor": 1000,
  "moeda": "BRL",
  "metodo": "pix",
  "tipo": "pix",
  "pix_chave": "12345678909",
  "pix_tipo": "cpf",
  "referencia": "wd_a1b2c3d4",
  "gateway": {
    "status": "QUEUED"
  },
  "cliente": {
    "nome": "Maria Souza",
    "email": "maria@email.com",
    "cpf": "12345678900"
  }
}

Saldo da conta

Endpoint planejado, ainda nao disponivel no backend atual.

Webhooks

Configure sua URL de webhook no painel (ou envie callback ao criar a cobranca).

Assinatura: header X-Magicpay-Signature com sha256= + HMAC-SHA256 do corpo usando sua API key.

{
  "id": 42,
  "status": "pago",
  "valor": 2500,
  "moeda": "BRL",
  "metodo": "pix",
  "descricao": "Pedido #123",
  "referencia": "ch_a1b2c3d4",
  "pago_em": "2025-12-04 10:05:10",
  "falhou_em": null,
  "estornado_em": null
}