Documentação da API

Introdução

Bem-vindo à documentação completa da nossa API. Você pode usar a MagoPay como processadora em um checkout transparente próprio, oferecendo Pix, boleto e cartão de crédito conforme as capacidades liberadas para a sua conta.

URL Base: https://api.magopay.com.br/api

Recursos Disponíveis

  • Autenticação: Geração de token JWT para acesso seguro aos endpoints
  • Pix: Criação de cobranças com QR Code e Pix Copia e Cola
  • Capacidades: Consulta dos meios e limites liberados para a conta
  • Boleto: Emissão de boleto, linha digitável, código de barras e PDF
  • Cartão: Cobranças à vista, parceladas e consulta/estorno
  • Saque: Solicitação de saques utilizando chaves PIX e cálculo de taxas
  • Webhooks: Notificações de callback para informar o status das transações

Autenticação

O endpoint de autenticação permite que os usuários façam login utilizando suas credenciais, recebendo um token JWT que deverá ser enviado no cabeçalho das requisições protegidas.

POST /api/auth/login

Parâmetros

Atributo Tipo Descrição
client_id string ID do cliente fornecido no cadastro
client_secret string Chave secreta do cliente para autenticação

Exemplo de Requisição

{
  "client_id": "seu_cliente_id",
  "client_secret": "seu_cliente_secreto"
}

Resposta de Sucesso

{
  "message": "Authentication successful.",
  "token": "seu_token_jwt",
  "user": {
    "id": 1,
    "name": "Nome do Usuário",
    "email": "email@exemplo.com",
    "client_id": "seu_cliente_id"
  }
}

Capacidades da conta

Consulte este endpoint depois da autenticação para montar o seu checkout somente com os meios, parcelamento e antecipação liberados para a conta. A resposta não expõe credenciais de processamento.

GET /api/account/capabilities
Requer autenticação: Authorization: Bearer {token}

Resposta de exemplo

{
  "data": {
    "account": { "id": 42, "status": "active", "currency": "BRL" },
    "paymentMethods": {
      "pix": { "enabled": true, "fallbackEnabled": true },
      "boleto": { "enabled": true },
      "card": {
        "enabled": true,
        "fallbackEnabled": true,
        "installments": { "enabled": true, "max": 12 },
        "anticipation": { "enabled": false, "minimumDays": 0 }
      }
    }
  }
}
Se um meio estiver com enabled: false, não o apresente no checkout e não envie a cobrança correspondente. As permissões são avaliadas novamente no momento da criação.

Depósito

Este endpoint permite criar um depósito e gerar um QR Code PIX para efetuar o pagamento.

POST /api/payments/deposit
Requer autenticação: Authorization: Bearer {token}

Parâmetros

Atributo Tipo Descrição
amount number Valor do depósito
external_id string ID único da transação externa (para controle idempotente)
clientCallbackUrl string URL para notificações de status do depósito
payer object Dados do pagador

Objeto Payer

Atributo Tipo Descrição
name string Nome completo do pagador
email string Email do pagador
document string Documento do pagador (CPF ou CNPJ)

Exemplo de Requisição

{
  "amount": 100.00,
  "external_id": "id_unico_12345",
  "clientCallbackUrl": "https://seuservidor.com/callback",
  "payer": {
    "name": "João da Silva",
    "email": "joao@example.com",
    "document": "12345678901"
  }
}

Resposta de Sucesso

{
  "message": "Deposit created successfully.",
  "qrCodeResponse": {
    "transactionId": "id_da_transacao",
    "status": "PENDING",
    "qrcode": "00020101021226930014br.gov.bcb.pix2571qrcode-h.pix...",
    "amount": 100.00
  }
}

Boleto

Emita um boleto pelo meio de pagamento liberado para a sua conta. A resposta inclui o PDF white-label, linha digitável, código de barras e, quando disponibilizado, Pix vinculado.

POST /api/v1/boletos
Requer autenticação: Authorization: Bearer {token}

Corpo da requisição

{
  "amount": 199.90,
  "dueDate": "2026-10-15",
  "description": "Pedido #1001",
  "clientCallbackUrl": "https://sualoja.com.br/webhooks/magopay",
  "payer": {
    "name": "Maria da Silva",
    "email": "maria@example.com",
    "document": "12345678901",
    "phone": "11999999999"
  }
}

Resposta de sucesso

{
  "message": "Boleto criado com sucesso.",
  "data": {
    "id": 781,
    "status": "PENDING",
    "amount": 199.90,
    "dueDate": "2026-10-15",
    "pdfUrl": "https://api.magopay.com.br/api/v1/boletos/781/pdf",
    "bankSlip": {
      "identificationField": "00190500954014481606906809350314337370000000100",
      "barCode": "00193373700000001000500940144816060680935031"
    },
    "pix": null
  }
}
O boleto precisa estar liberado e configurado para a conta. Consulte /api/account/capabilities antes de exibir esta opção.
GET /api/v1/boletos/{id}/identification-field

Consulta a linha digitável e o código de barras de um boleto pertencente à conta autenticada.

Cartão de crédito

Processe cartão de crédito diretamente no checkout do seu site. O endpoint aceita pagamento à vista, parcelamento quando liberado e pode usar contingência na ordem configurada para a conta.

POST /api/v1/card/payments
Requer autenticação: Authorization: Bearer {token}

Corpo da requisição

{
  "amount": 299.90,
  "description": "Pedido #1001",
  "externalReference": "pedido-1001",
  "clientCallbackUrl": "https://sualoja.com.br/webhooks/magopay",
  "dueDate": "2026-10-15",
  "installmentCount": 3,
  "passFeesToBuyer": true,
  "anticipate": false,
  "payer": {
    "name": "Maria da Silva",
    "email": "maria@example.com",
    "document": "12345678901",
    "phone": "11999999999",
    "postalCode": "01310100",
    "addressNumber": "100"
  },
  "creditCard": {
    "holderName": "MARIA DA SILVA",
    "number": "4111111111111111",
    "expiryMonth": "12",
    "expiryYear": "2028",
    "ccv": "123"
  }
}

Resposta de sucesso

{
  "message": "Pagamento criado com sucesso.",
  "data": {
    "id": 981,
    "amount": 299.90,
    "status": "CONFIRMED",
    "installmentCount": 3,
    "pricing": {
      "chargedAmount": 329.40,
      "installmentAmount": 109.80,
      "buyerFee": 29.50,
      "installments": 3
    }
  }
}
Nunca armazene o cartão no seu sistema. Envie os dados somente via HTTPS, use idempotência no seu pedido e aguarde o webhook para atualizar o pedido como pago.
GET /api/v1/card/payments/{id}

Consulta o status e as datas financeiras de uma cobrança de cartão da conta autenticada.

POST /api/v1/card/payments/{id}/refund

Solicita o estorno total de uma cobrança de cartão pertencente à conta autenticada.

TEF presencial para ERP

Integre o caixa Windows do seu ERP a sessões Pix e cartão presencial usando um contrato único. O cliente não precisa conhecer a infraestrutura de processamento por trás da MagoPay.

POST /api/tef/sessions
Requer autenticação e o header Idempotency-Key

Criar Pix

{
  "payment_method": "pix",
  "amount": 19.90,
  "external_reference": "pedido-1001",
  "order_reference": "1001",
  "callback_url": "https://erp.exemplo.com.br/webhooks/magopay",
  "payer": {
    "name": "Cliente de balcão",
    "email": "cliente@exemplo.com",
    "document": "12345678901"
  },
  "metadata": {"pdv": "caixa-01"}
}

A resposta contém data.pix.qrCode e data.pix.copyAndPaste. Mostre ambos no ERP e consulte a sessão até APPROVED.

Criar cartão presencial

{
  "payment_method": "card",
  "amount": 199.90,
  "installments": 3,
  "external_reference": "pedido-1001",
  "order_reference": "1001",
  "callback_url": "https://erp.exemplo.com.br/webhooks/magopay"
}

O cartão começa em WAITING_LOCAL. O ERP inicia o agente local com POST http://127.0.0.1:3699/session/start. Após a resposta do TEF, envie o resultado ao bridge em /session/result. Nunca marque a venda como paga antes de receber APPROVED.

GET/api/tef/sessions/{id}

Consulta a sessão da conta autenticada. O Pix é sincronizado automaticamente com o depósito.

POST/api/tef/sessions/{id}/start

Inicia uma sessão de cartão no agente local. O agente deve enviar agent_id e local_terminal_id para rastreabilidade.

POST/api/tef/sessions/{id}/result

Registra approved, declined, failed, cancelled ou processing, além de NSU, autorização e últimos quatro dígitos quando disponíveis.

POST/api/tef/sessions/{id}/cancel

Solicita cancelamento de uma sessão de cartão ainda não finalizada.

Para o cartão físico, instale o agente Windows fornecido no projeto e homologue o adaptador do ambiente TEF do cliente. O bridge não simula aprovações e o ERP nunca deve enviar número, CVV, senha ou trilha do cartão para a API.

Saque

Este endpoint permite solicitar saque utilizando uma chave PIX, com verificação de saldo, cálculo de taxas e atualização do status da transação.

POST /api/withdrawals/withdraw
Requer autenticação: Authorization: Bearer {token}

Parâmetros

Atributo Tipo Descrição
amount number Valor do saque
external_id string ID único da transação externa
pix_key string Chave PIX do destinatário
key_type string Tipo da chave (EMAIL, CPF, CNPJ ou PHONE)
description string Descrição opcional do saque
clientCallbackUrl string URL para notificações de status do saque

Exemplo de Requisição

{
  "amount": 50.00,
  "external_id": "external-12345",
  "pix_key": "exemplo@pix.com",
  "key_type": "EMAIL",
  "description": "Saque referente ao pedido #123",
  "clientCallbackUrl": "https://seuservidor.com/callback"
}

Resposta de Sucesso

{
  "transaction_id": "transaction-67890",
  "status": "PENDING",
  "amount": 50.00,
  "fee": 2.50
}

Webhooks

Os webhooks permitem que seu sistema receba notificações em tempo real sobre atualizações no status das transações (depósito e saque). Utilize a URL de callback (clientCallbackUrl) para receber os updates.

Webhook de Depósito

Payload - Status PENDING

{
  "transaction_id": "id_da_transacao",
  "status": "PENDING",
  "amount": 100.00,
  "type": "Deposit"
}

Payload - Status COMPLETED

{
  "transaction_id": "id_da_transacao",
  "status": "COMPLETED",
  "amount": 100.00,
  "type": "Deposit"
}
Webhook de Saque

Payload - Status PENDING

{
  "transaction_id": "transaction-67890",
  "status": "PENDING",
  "amount": 50.00,
  "type": "Withdraw"
}

Payload - Status COMPLETED

{
  "transaction_id": "transaction-67890",
  "status": "COMPLETED",
  "amount": 50.00,
  "type": "Withdraw"
}

Códigos de Erro

A API utiliza códigos HTTP padrão para indicar o resultado das operações. A seguir, os principais códigos de erro e suas descrições.

200
OK
Requisição processada com sucesso
400
Bad Request
Dados inválidos ou campos obrigatórios ausentes
401
Unauthorized
Credenciais inválidas ou token não enviado
404
Not Found
Recurso não encontrado ou rota incorreta
500
Internal Server Error
Erro no servidor durante o processamento
Exemplo de Resposta de Erro 
{
  "error": "Validation failed",
  "message": "Os campos fornecidos são inválidos",
  "details": {
    "amount": ["O campo amount é obrigatório"],
    "payer.email": ["O email deve ser válido"]
  }
}