Visão geral

API REST sobre HTTPS. Corpo em JSON, resposta em JSON, valores em reais com centavos (12.34, não 1234). Datas em ISO 8601 UTC.

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

Autenticação

Toda chamada leva a sua chave de API. Você a cria em Painel → Integração → Chaves de API. A chave aparece uma vez só no momento em que é criada — guardamos apenas o hash dela, então não temos como mostrá-la de novo. Se perdeu, revogue e crie outra.

Authorization: Bearer sua_chave_aqui

Também aceitamos o cabeçalho alternativo, para integrações antigas:

X-API-Key: sua_chave_aqui

Erros e limites

Todo erro devolve o mesmo formato:

{
  "error": {
    "code": "validation_error",
    "message": "Confira os campos enviados."
  }
}

Criar cobrança Pix

curl -X POST https://mercosulpay.com/api/public/v1/pix/charges \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 480.00,
    "description": "Diária 12/09 — quarto 214",
    "reference_id": "RES-88213"
  }'

{
  "id": "3f1c…",
  "status": "pending",
  "amount": 480.00,
  "fee": 4.32,
  "net_amount": 475.68,
  "reference_id": "RES-88213",
  "qr_code": "00020126…",
  "qr_code_image": "data:image/png;base64,…",
  "created_at": "2026-09-01T18:20:11.000Z"
}

qr_code é o copia-e-cola; qr_code_image já vem pronto para colocar num <img src>. A cobrança nasce pending — o dinheiro só é seu quando ela vira completed, e é o webhook que avisa.

Consultar cobranças

Aceita ?limit= (padrão 25, teto 100) e ?status= (pending, completed, failed, refunded). Devolve as mais recentes primeiro.

Uma cobrança, com description, net_amount e updated_at.

Enviar Pix (saque)

POST /v1/pix/withdrawals

{
  "amount": 100.00,
  "pix_key": "11999999999",
  "pix_key_type": "phone",
  "recipient_document": "12345678901",
  "reference_id": "seu-id-unico"
}

Saldo

Saldo disponível da conta. É o que um saque pode consumir agora.

Webhooks

Você cadastra a URL em Painel → Integração → Webhooks e recebe um segredo junto. Eventos que enviamos:

• pix.received — entrou dinheiro. É este que confirma a venda.
• pix.sent — o seu saque saiu.
• pix.refunded — houve estorno.
• crypto.received · crypto.sent — o equivalente em cripto.

x-mercosulpay-event:     pix.received
x-mercosulpay-delivery:  <id único desta entrega>
x-mercosulpay-timestamp: 1788300000
x-mercosulpay-signature: sha256=<hex>

Conferir a assinatura

Confira sempre. Sem isso, qualquer um que descubra a sua URL pode dizer que uma venda foi paga — e a sua recepção libera o quarto.

A assinatura é HMAC-SHA256 sobre a string timestamp + "." + corpo_bruto, em hexadecimal minúsculo, com o prefixo sha256=.

const crypto = require('crypto');

function confere(req, segredo) {
  // O corpo BRUTO, exatamente como chegou. Se você deixar o framework
  // transformar em objeto e reserializar, um espaço a mais muda o hash
  // e a assinatura válida passa a ser recusada.
  const bruto = req.rawBody.toString('utf8');
  const ts = req.get('x-mercosulpay-timestamp');

  // Recusa entrega velha: sem isto, uma entrega capturada hoje pode ser
  // reenviada daqui a meses, com a assinatura ainda batendo.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const esperado = 'sha256=' + crypto
    .createHmac('sha256', segredo)
    .update(`${ts}.${bruto}`)
    .digest('hex');

  const a = Buffer.from(esperado);
  const b = Buffer.from(req.get('x-mercosulpay-signature') || '');
  // Comparação em tempo constante: `===` vaza, pelo tempo, quantos
  // caracteres o atacante já acertou.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Detalhes que mordem

Estão aqui porque você vai encontrá-los de qualquer jeito. Melhor agora do que no fechamento do mês.

net_amount significa coisas diferentes em dois lugares

A cobrança nasce pending

Criar cobrança não é receber. Só completed significa dinheiro na conta. Liberar produto no 201 é liberar contra um QR que talvez ninguém pague.

Valores são reais, não centavos

480.00, não 48000. Dentro do nosso sistema tudo é centavo inteiro; a conversão acontece na borda. Se o seu lado trabalha em centavos, converta na entrada e na saída, e nunca com float.

Cobrança em outra moeda

currency: "PYG" faz o valor ser interpretado em guaranis, mas o Pix continua sendo em reais — o pagador paga o equivalente pela cotação do momento, que fica congelada na transação. O teto por operação também é o daquela moeda.

Cripto (USDT)

asset obrigatório (USDT_BSC) e amount_brl — você pede em reais e nós cobramos o equivalente.

asset, address e amount.

Ficou faltando algo?

Escreva para contato@mercosulpay.com. Se você precisou adivinhar alguma coisa nesta página, isso é um defeito da página — conte qual, que a gente corrige.