Getting started
Create account
Open your account at abrirconta.magen.com.br. After approval you receive:
- Bearer token, used in all requests. See Authentication.
- Base URL,
https://api.magen.processamento.com/v1.
Store the token in a vault (Google Secret Manager, AWS Secrets, etc). Never commit it to a repository or expose it in the front-end.
Test authentication
To confirm the token works, check the account balance using the GET /user/balance endpoint.
curl https://api.magen.processamento.com/v1/user/balance \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json"const res = await fetch('https://api.magen.processamento.com/v1/user/balance', {
headers: {
Authorization: `Bearer ${process.env.MAGEN_TOKEN}`,
'Content-Type': 'application/json',
},
});
const balance = await res.json();If the JSON with the balance comes back, you are authenticated. If it returns 401, check the token (whitespace, encoding) or contact support. See HTTP codes in the glossary.
Create the first Pix charge
Create a charge via POST /pix. Full schema in the reference.
curl -X POST https://api.magen.processamento.com/v1/pix \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 10.90,
"generatedName": "João da Silva",
"generatedDocument": "12345678909",
"callbackUrl": "https://seusite.com.br/webhooks/magen",
"clientReference": "pedido-2025-001"
}'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: 10.90,
generatedName: 'João da Silva',
generatedDocument: '12345678909',
callbackUrl: 'https://seusite.com.br/webhooks/magen',
clientReference: 'pedido-2025-001',
}),
});
const charge = await res.json();The response brings qrCodeText (copy-and-paste), qrCodeUrl and the transaction id. Each field is explained in the glossary.
Amounts are always in reais (BRL), not cents. 10.90 is R$ 10.90.
Receive the callback
When the payer completes the Pix, Magen sends a POST to the provided callbackUrl with the updated transaction object (status: "COMPLETED"). Respond with 2xx within 5 seconds.
POST /webhooks/magen
Content-Type: application/json
{
"id": "MAGEN20251123104518DF75D20A8F",
"status": "COMPLETED",
"amount": 10.90,
"clientReference": "pedido-2025-001",
"endToEndId": "E18236120202511231046s1235ee7",
"paidAt": "2025-11-23T10:46:26.986Z"
}Retry details, full payload and security in Webhooks. To inspect or manually resend, use GET /user/callbacks.
Conceitos
Antes de fazer a primeira chamada, vale entender o que a API cobre, como os endpoints são agrupados e o que representa uma transação na Magen. Esta página é o mapa mental que você vai usar em todas as outras.
Autenticação
Toda chamada à Magen usa Bearer token. Esta página mostra como enviar, onde guardar com segurança e o que fazer quando aparecer um 401 ou 403. Token é como senha, trata como tal.