Receba por PIX
em 3 linhas de código

Introdução

A API do RT Payments gera cobranças PIX pra você usar em site, bot de Telegram, app, checkout próprio — o que for. Você chama um endpoint e recebe o QR Code e o código copia-e-cola prontos.

Toda requisição usa JSON sobre HTTPS. Valores em dinheiro são sempre inteiros em centavos — 2990 quer dizer R$ 29,90. Isso evita erro de arredondamento com casas decimais.

Como funciona

Autenticação

Toda chamada leva sua chave no header Authorization, no formato Bearer:

Authorization: Bearer rtp_live_sua_chave_aqui

Você pode ter até 5 chaves ativas ao mesmo tempo — útil pra separar ambientes ou sistemas.

Taxas e comissão

Em cada venda aprovada existem dois custos, e eles são diferentes:

Não tem mensalidade, taxa de adesão nem cobrança sobre cobrança gerada que não foi paga. Se o cliente não pagar, você não paga nada. A resposta da API já traz commission e net_amount pra você saber exatamente quanto vai receber — net_amount já é o valor descontada a nossa comissão.

Criar cobrança

Gera uma cobrança PIX e devolve o QR Code pronto pra mostrar.

Parâmetros

Exemplo

Resposta

{
  "id": "a3f1c92b8e447d20b1c5e0aa",
  "status": "pending",
  "amount": 2990,
  "commission": 85,
  "net_amount": 2905,
  "description": "Plano mensal",
  "external_id": "pedido-1234",
  "qr_code": "00020101021226810014br.gov.bcb.pix...",
  "qr_code_base64": "iVBORw0KGgoAAAANSUhEUg...",
  "qr_code_image": "https://payments.rtsystems.app/qr/a3f1c92b8e447d20b1c5e0aa.png",
  "checkout_url": "https://payments.rtsystems.app/t/a3f1c92b8e447d20b1c5e0aa",
  "created_at": "2026-09-01T14:22:10.442Z",
  "expires_at": "2026-09-01T14:52:10.442Z"
}

Você tem três jeitos de mostrar isso pro cliente: renderizar o qr_code como QR na sua página, usar a imagem pronta de qr_code_image, ou simplesmente mandar ele pro checkout_url.

Consultar cobrança

Devolve a situação atual. Se ainda estiver pendente, conferimos no gateway antes de responder — o status vem sempre fresco.

curl https://payments.rtsystems.app/v1/pix/a3f1c92b8e447d20b1c5e0aa \
  -H "Authorization: Bearer rtp_live_sua_chave_aqui"

Listar cobranças

curl "https://payments.rtsystems.app/v1/pix?status=paid&limit=50" \
  -H "Authorization: Bearer rtp_live_sua_chave_aqui"

Checkout pronto

Se você não quiser desenhar tela de pagamento, use o checkout_url que vem em toda cobrança. É uma página hospedada por nós, responsiva, com QR Code, botão de copiar, contador de expiração e confirmação automática quando o PIX cai.

// Depois de criar a cobrança, é só redirecionar:
res.redirect(pix.checkout_url);

A página se atualiza sozinha quando o pagamento entra — o cliente vê o comprovante sem precisar recarregar nada.

Dados da conta

Confirma que a chave é válida e mostra sua configuração atual. Bom pra testar a integração.

{
  "id": "AYZVZR",
  "name": "Loja do Kawan",
  "email": "voce@email.com",
  "status": "active",
  "commission": { "percent": 1.5, "fixed": 40, "mode": "split" },
  "gateway": { "provider": "pushinpay", "account_id": "A0FE...0BB9", "status": "connected" },
  "webhook_url": "https://seusite.com/webhook/rtpay",
  "stats": { "approved_count": 128, "approved_amount": 964500 }
}

Saldo

Consulta o saldo da sua conta no gateway. Valores em centavos.

{ "available": 45320, "total": 51200, "blocked": 5880, "currency": "BRL" }

Webhooks

Cadastre uma URL no painel e mandamos um POST nela quando o pagamento for aprovado. É assim que seu sistema fica sabendo — sem ficar consultando.

Eventos

Corpo enviado

{
  "event": "payment.paid",
  "created_at": "2026-09-01T14:31:02.180Z",
  "data": {
    "id": "a3f1c92b8e447d20b1c5e0aa",
    "status": "paid",
    "amount": 2990,
    "commission": 85,
    "net_amount": 2905,
    "external_id": "pedido-1234",
    "payer_name": "Joao da Silva",
    "end_to_end_id": "E1234567820260901143100abcdef123",
    "paid_at": "2026-09-01T14:31:01.000Z",
    "created_at": "2026-09-01T14:22:10.442Z"
  }
}

Headers

Reentrega

Responda HTTP 2xx pra confirmar. Se não responder, tentamos de novo até 6 vezes com espera crescente: 30 segundos, 2 minutos, 5, 15, 1 hora e 3 horas. Depois disso a entrega fica marcada como falha, e você pode reenviar manualmente no painel.

Validar a assinatura

Sem validar, qualquer um que descobrir sua URL consegue fingir um pagamento aprovado. Sempre valide.

O header vem assim: X-RTPay-Signature: t=1756742100,v1=9f86d081.... Você recalcula o HMAC SHA-256 de t + "." + corpo_bruto usando o segredo do webhook (está no painel) e compara com o v1.

Status de uma cobrança

Erros

Erro sempre volta no mesmo formato, com o HTTP correspondente:

{
  "error": {
    "code": "valor_muito_baixo",
    "message": "O valor mínimo é 100 centavos."
  }
}

Limites

Passou do limite? Volta HTTP 429. Espere e tente de novo dobrando o intervalo a cada falha. Se seu volume for maior que isso, fala com a gente que ajustamos.