Documentação da API MercosulPay

A API MercosulPay permite que lojistas gerem cobranças Pix e cripto, acompanhem pagamentos e consultem saldo diretamente do próprio sistema, e-commerce ou ERP. Toda a comunicação é REST com JSON sobre HTTPS.

Base URL
https://mercosulpay.com/api/public/v1

Para gerar suas chaves, entre na sua conta e acesse Gateway → Nova chave.

Autenticação

Envie sua chave secreta no header Authorization em todas as requisições. A chave é exibida uma única vez na criação e armazenamos apenas o hash SHA-256 — não é possível recuperá-la depois.

Authorization: Bearer otp_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

• Chaves otp_test_ são de homologação; otp_live_ movimentam dinheiro real.
• Cada chave pertence a uma conta e só enxerga os dados dessa conta.
• Revogue uma chave a qualquer momento no painel — o bloqueio é imediato.

Segurança da integração

Todas as chamadas são registradas (chave, rota, status, IP e horário) e limitadas a 120 requisições por minuto por chave. Requisições sem HTTPS ou com chave revogada são rejeitadas com 401. Saques só funcionam com chave live e conta com KYC aprovado.

Criar cobrança Pix

Gera um QR Code Pix dinâmico (Copia e Cola). O valor cai na sua conta MercosulPay assim que o pagador concluir o pagamento, já com a taxa descontada.

POST https://mercosulpay.com/api/public/v1/pix/charges

{
  "amount": 149.90,
  "description": "Pedido #1042",
  "reference_id": "1042"
}

Resposta 201

{
  "id": "8f0c...c3a1",
  "status": "pending",
  "amount": 149.9,
  "fee": 4.5,
  "net_amount": 145.4,
  "reference_id": "1042",
  "qr_code": "00020101021226...6304ABCD",
  "qr_code_image": "https://...",
  "created_at": "2026-07-30T18:20:11.000Z"
}

Exemplo com cURL

curl -X POST https://mercosulpay.com/api/public/v1/pix/charges \
  -H "Authorization: Bearer $MERCOSULPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 149.90, "description": "Pedido #1042", "reference_id": "1042"}'

Exemplo com Node.js

const res = await fetch("https://mercosulpay.com/api/public/v1/pix/charges", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MERCOSULPAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 149.9, reference_id: "1042" }),
});
const charge = await res.json();

Consultar cobrança

GET https://mercosulpay.com/api/public/v1/pix/charges/{id}

Retorna o status atual: pending, completed, failed ou refunded. Use webhooks para tempo real e a consulta apenas como conciliação.

Listar cobranças

GET https://mercosulpay.com/api/public/v1/pix/charges?limit=25&status=completed

limit aceita de 1 a 100 (padrão 25). status é opcional.

Saque Pix

Envie Pix diretamente para uma chave do recebedor. O valor + taxa são debitados do saldo BRL da conta. Só é permitido com chave otp_live_, conta com KYC aprovado e saldo suficiente.

POST https://mercosulpay.com/api/public/v1/pix/withdrawals

{
  "amount": 250.00,
  "pix_key": "11999999999",
  "pix_key_type": "phone",
  "description": "Repasse semanal #42",
  "reference_id": "repasse-42"
}

Resposta 201

{
  "id": "9a1b...e4c2",
  "status": "pending",
  "amount": 250.0,
  "fee": 5.0,
  "total_debit": 255.0,
  "net_amount": 245.0,
  "reference_id": "repasse-42",
  "created_at": "2026-07-30T18:20:11.000Z"
}

Tipos de chave Pix suportados

• cpf — apenas dígitos, 11 caracteres
• cnpj — apenas dígitos, 14 caracteres
• email — e-mail válido
• phone — formato internacional, ex: +5511999999999
• evp — chave aleatória (UUID)
• emv — Copia e Cola estático (extraímos a ch Pix automaticamente; QR dinâmico não é aceito)

Exemplo com cURL

curl -X POST https://mercosulpay.com/api/public/v1/pix/withdrawals \
  -H "Authorization: Bearer $MERCOSULPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 250, "pix_key": "+5511999999999", "pix_key_type": "phone", "reference_id": "repasse-42"}'

Cripto — visão geral

Além do Pix, a MercosulPay aceita recebimento e envio em criptomoedas. A liquidação on-chain é feita pelo nosso provedor e o saldo fica na sua conta MercosulPay, separado por ativo. A integração segue o mesmo padrão do Pix: mesma chave de API, mesmos webhooks assinados e mesmos códigos de erro.

Referência oficial da rede (BEP-20)

• Cobranças e saques cripto exigem conta com KYC aprovado e chave otp_live_.
• Só operamos USDT BEP-20 na BNB Smart Chain. Endereços TRC-20 (rede TRON, iniciados com T) não são aceitos e envios nessa rede são irrecuperáveis.
• Valide sempre que o endereço começa com 0x e tem 42 caracteres antes de enviar.
• A taxa cripto padrão é de 1% na entrada e 1% na saída, isenta para contas com aplicação ativa.

Criar cobrança cripto

Você informa o valor em BRL e devolvemos o endereço da carteira, o valor equivalente no ativo e um link de pagamento pronto para exibir ao cliente. O crédito é confirmado por webhook quando a rede confirmar.

POST https://mercosulpay.com/api/public/v1/crypto/charges

{
  "asset": "USDT_BSC",
  "amount_brl": 500.00,
  "description": "Pedido #1042",
  "reference_id": "1042"
}

Resposta 201

{
  "id": "4d21...a90f",
  "status": "pending",
  "asset": "USDT",
  "network": "BNB Smart Chain (BEP-20)",
  "amount": "92.41",
  "amount_brl": 500,
  "address": "0x9f1a3c7d5e2b48a0c6d1f70b3e8a92d4c5b6e7f8",
  "invoice_url": "https://plisio.net/invoice/...",
  "expires_at": "1785600000",
  "reference_id": "1042",
  "created_at": "2026-08-03T17:20:11.000Z"
}

Exemplo com cURL

curl -X POST https://mercosulpay.com/api/public/v1/crypto/charges \
  -H "Authorization: Bearer $MERCOSULPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset": "USDT_BSC", "amount_brl": 500, "reference_id": "1042"}'

Listar cobranças cripto

GET https://mercosulpay.com/api/public/v1/crypto/charges?limit=25&status=completed

Mesmos filtros do Pix. Cada item traz asset, amount (no ativo), amount_brl, address e reference_id.

Saque cripto (on-chain)

Envia o ativo do seu saldo MercosulPay para uma carteira externa. O valor + taxa são debitados do saldo do ativo; se a rede recusar, o saldo é devolvido automaticamente e a transação fica como failed.

POST https://mercosulpay.com/api/public/v1/crypto/withdrawals

{
  "asset": "USDT_BSC",
  "address": "0x9f1a3c7d5e2b48a0c6d1f70b3e8a92d4c5b6e7f8",
  "amount": 120.00,
  "reference_id": "payout-88"
}

Resposta 201

{
  "id": "77ab...12cd",
  "status": "pending",
  "asset": "USDT",
  "amount": 120,
  "fee": 1.2,
  "total_debit": 121.2,
  "tx_url": "https://bscscan.com/tx/...",
  "reference_id": "payout-88",
  "created_at": "2026-08-03T17:22:40.000Z"
}

• Confira o endereço antes de enviar: operações on-chain são irreversíveis.
• Saldo insuficiente retorna 422 insufficient_funds sem debitar nada.
• Acompanhe a confirmação pelo webhook crypto.sent ou pelo tx_url.

Consultar saldo

GET https://mercosulpay.com/api/public/v1/balance

{
  "brl": 4628.63,
  "btc": 0.00412,
  "usdt": 320.5,
  "updated_at": "2026-07-30T18:20:11.000Z"
}

Webhooks

Cadastre a URL do seu sistema no painel para receber notificações de pagamento. Enviamos um POST com JSON e a assinatura HMAC-SHA256 do corpo no header x-mercosulpay-signature, calculada com o segredo do seu webhook.

POST https://seu-site.com/webhooks/mercosulpay
x-mercosulpay-signature: 9f86d0...

{
  "event": "pix.received",
  "data": {
    "id": "8f0c...c3a1",
    "status": "completed",
    "amount": 149.9,
    "reference_id": "1042",
    "paid_at": "2026-07-30T18:25:02.000Z"
  }
}

Validando a assinatura (Node.js)

import { createHmac, timingSafeEqual } from "crypto";

const raw = await req.text(); // use o corpo bruto, sem parse
const expected = createHmac("sha256", process.env.MERCOSULPAY_WEBHOOK_SECRET)
  .update(raw)
  .digest("hex");

const received = req.headers.get("x-mercosulpay-signature") ?? "";
const valid =
  received.length === expected.length &&
  timingSafeEqual(Buffer.from(received), Buffer.from(expected));

if (!valid) return new Response("Unauthorized", { status: 401 });

Eventos cripto

{
  "event": "crypto.received",
  "data": {
    "id": "4d21...a90f",
    "status": "completed",
    "asset": "USDT",
    "network": "BNB Smart Chain (BEP-20)",
    "amount": 92.41,
    "amount_brl": 500,
    "confirmations": 20,
    "tx_url": "https://bscscan.com/tx/...",
    "reference_id": "1042",
    "paid_at": "2026-08-03T17:31:02.000Z"
  }
}

• Eventos disponíveis: pix.received, pix.sent, pix.refunded, crypto.received, crypto.sent e crypto.failed.
• Sempre valide a assinatura antes de liberar o pedido.
• Responda 200 em até 10 segundos; reenviamos em caso de falha.
• Trate eventos duplicados usando o id da cobrança (idempotência).
• Em cripto, só libere o pedido quando o evento chegar com status: "completed".

Erros e limites

{
  "error": {
    "code": "validation_error",
    "message": "Parâmetros inválidos.",
    "details": { "amount": ["Number must be greater than 0"] }
  }
}