Receive Pix payment

Generate charge

Endpoint: POST /pix. Only amount is required; the other fields enrich the QR and reconciliation.

curl -X POST https://api.magen.processamento.com/v1/pix \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 99.90,
    "generatedName": "João da Silva",
    "generatedDocument": "12345678909",
    "callbackUrl": "https://seusite.com.br/webhooks/magen",
    "clientReference": "pedido-2025-001",
    "virtualAccount": "loja-rj-01",
    "expiresIn": 600
  }'

const res = await fetch('https://api.magen.processamento.com/v1/pix', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAGEN_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 99.90,
    generatedName: 'João da Silva',
    generatedDocument: '12345678909',
    callbackUrl: 'https://seusite.com.br/webhooks/magen',
    clientReference: 'pedido-2025-001',
    virtualAccount: 'loja-rj-01',
    expiresIn: 600,
  }),
});
const charge = await res.json();

import os, requests

res = requests.post(
    'https://api.magen.processamento.com/v1/pix',
    headers={
        'Authorization': f'Bearer {os.environ["MAGEN_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': 99.90,
        'generatedName': 'João da Silva',
        'generatedDocument': '12345678909',
        'callbackUrl': 'https://seusite.com.br/webhooks/magen',
        'clientReference': 'pedido-2025-001',
        'virtualAccount': 'loja-rj-01',
        'expiresIn': 600,
    },
)
charge = res.json()

body := strings.NewReader(`{
  "amount": 99.90,
  "generatedName": "João da Silva",
  "generatedDocument": "12345678909",
  "callbackUrl": "https://seusite.com.br/webhooks/magen",
  "clientReference": "pedido-2025-001",
  "virtualAccount": "loja-rj-01",
  "expiresIn": 600
}`)

req, _ := http.NewRequest("POST", "https://api.magen.processamento.com/v1/pix", body)
req.Header.Set("Authorization", "Bearer " + os.Getenv("MAGEN_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

<?php
$ch = curl_init('https://api.magen.processamento.com/v1/pix');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('MAGEN_TOKEN'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 99.90,
    'generatedName' => 'João da Silva',
    'generatedDocument' => '12345678909',
    'callbackUrl' => 'https://seusite.com.br/webhooks/magen',
    'clientReference' => 'pedido-2025-001',
    'virtualAccount' => 'loja-rj-01',
    'expiresIn' => 600,
  ]),
]);
$charge = json_decode(curl_exec($ch), true);

Response:

{
  "id": "MAGEN20250817215911F49RDOBJ",
  "status": "PENDING",
  "amount": 99.90,
  "qrCodeText": "00020126870014br.gov.bcb.pix...",
  "qrCodeUrl": "https://api.magen.processamento.com/v1/pix/qr-code/MAGEN20250817215911F49RDOBJ",
  "clientReference": "pedido-2025-001",
  "virtualAccount": "loja-rj-01",
  "expiresAt": "2025-08-17T22:00:00.000Z"
}

Display QR Code to customer

Two ways:

Direct image, use qrCodeUrl in <img>:

<img src="https://api.magen.processamento.com/v1/pix/qr-code/MAGEN2025..." />

Copy-and-paste, display qrCodeText in an input with a button:

<input value="00020126870014br.gov.bcb.pix2565..." readonly />
<button onclick="navigator.clipboard.writeText(qrCodeText)">Copy</button>

Magen only generates dynamic QR. Static QR is not supported.

Receive callback when paid

When the customer completes the Pix, Magen sends a POST to your callbackUrl:

{
  "id": "MAGEN20250817215911F49RDOBJ",
  "type": "DEPOSIT",
  "status": "COMPLETED",
  "amount": 99.90,
  "clientReference": "pedido-2025-001",
  "virtualAccount": "loja-rj-01",
  "endToEndId": "E60746948202508172200X7H4K2P9M5",
  "paidAt": "2025-08-17T22:00:12.000Z"
}

Sample handler:

import express from 'express';
const app = express();

app.post('/webhooks/magen', express.json(), async (req, res) => {
  const tx = req.body;

  if (await isProcessed(tx.id, tx.status)) return res.status(200).end();

  if (tx.type === 'DEPOSIT' && tx.status === 'COMPLETED') {
    await markOrderPaid(tx.clientReference, tx);
  }

  res.status(204).end();
});

from flask import Flask, request
app = Flask(__name__)

@app.post('/webhooks/magen')
def magen_webhook():
    tx = request.get_json()
    if is_processed(tx['id'], tx['status']):
        return '', 200
    if tx['type'] == 'DEPOSIT' and tx['status'] == 'COMPLETED':
        mark_order_paid(tx['clientReference'], tx)
    return '', 204

http.HandleFunc("/webhooks/magen", func(w http.ResponseWriter, r *http.Request) {
    var tx Transaction
    if err := json.NewDecoder(r.Body).Decode(&tx); err != nil {
        w.WriteHeader(http.StatusBadRequest)
        return
    }
    if isProcessed(tx.ID, tx.Status) {
        w.WriteHeader(http.StatusOK)
        return
    }
    if tx.Type == "DEPOSIT" && tx.Status == "COMPLETED" {
        markOrderPaid(tx.ClientReference, tx)
    }
    w.WriteHeader(http.StatusNoContent)
})

<?php
$tx = json_decode(file_get_contents('php://input'), true);

if (isProcessed($tx['id'], $tx['status'])) {
    http_response_code(200);
    exit;
}

if ($tx['type'] === 'DEPOSIT' && $tx['status'] === 'COMPLETED') {
    markOrderPaid($tx['clientReference'], $tx);
}

http_response_code(204);

Respond within 5 seconds with 2xx. Otherwise, Magen starts retrying (up to 72 attempts with exponential backoff). Details in Webhooks.

Polling fallback

If the callback does not arrive, query directly via GET /pix. It accepts id, clientReference, endToEndId or virtualAccount, use only one.

curl "https://api.magen.processamento.com/v1/pix?clientReference=pedido-2025-001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

const res = await fetch(
  `https://api.magen.processamento.com/v1/pix?clientReference=pedido-2025-001`,
  {
    headers: {
      Authorization: `Bearer ${process.env.MAGEN_TOKEN}`,
      'Content-Type': 'application/json',
    },
  },
);
const charge = await res.json();

res = requests.get(
    'https://api.magen.processamento.com/v1/pix',
    params={'clientReference': 'pedido-2025-001'},
    headers={
        'Authorization': f'Bearer {os.environ["MAGEN_TOKEN"]}',
        'Content-Type': 'application/json',
    },
)

Polling should be a fallback. Configure the callback as the primary source.

Receipt

After payment, download the official receipt via GET /proof/{id}:

curl "https://api.magen.processamento.com/v1/proof/MAGEN20250817215911F49RDOBJ" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"