API Reference

Documentação da API

Integre pagamentos PIX na sua aplicação. Dois modos de integração: REST v1 (headers, recomendado) e Gateway (credenciais no body/query).

Autenticação REST API v1 Gateway (legado)Webhooks Erros Comuns Taxas

Base URLs

REST API v1 — Recomendada

https://api.razepag.com/api

Exemplo: https://api.razepag.com/api/v1/pix/charge

Gateway (legado)

https://api.razepag.com/api/api— nota: duplo /api

Exemplo: https://api.razepag.com/api/api/v1/c1/qrcode.php

O caminho /api é obrigatório. Esquecer o /api retorna 404 — este é o erro mais comum.

Autenticação

A API não usa JWT nem Bearer Token. Credenciais são client_id + client_secret, geradas no Dashboard.

Como obter credenciais

Acesse o Dashboard → API → Credenciais
Clique em Criar nova credencial
Copie o client_id e client_secret — o secret é exibido uma única vez
Opcionalmente, configure whitelist de IPs permitidos

Headers aceitos — REST API v1

Header	Também aceito	Obrigatório
`client_id`	`client-id`	Sim
`client_secret`	`client-secret`	Sim
`Content-Type`	`—`	Sim (POST/PATCH)

NÃO usar — causam erro 401

✗Authorization: Bearer

✗x-api-key

✗apikey

✗token

REST API v1

client_id + client_secret nos headers

API moderna com autenticação via headers HTTP. Recomendada para novas integrações.

Base: https://api.razepag.com/api

POST/v1/pix/chargeCriar cobrança PIX (QR Code)

GET/v1/pix/charge/:idConsultar status da cobrança

GET/v1/balanceConsultar saldo

GET/v1/transactionsListar transações

POST/v1/transferTransferência interna (grátis) ou por chave PIX

2.1 Criar Cobrança PIX

201 Created

curl -X POST https://api.razepag.com/api/v1/pix/charge \
  -H "client_id: SEU_CLIENT_ID" \
  -H "client_secret: SEU_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "description": "Pedido #1234",
    "externalReference": "order-456",
    "customerName": "João Silva",
    "customerEmail": "joao@email.com"
  }'

Resposta — 201 Created

{
  "data": {
    "id": "uuid-da-transacao",
    "type": "DEPOSIT",
    "status": "PENDING",
    "amount": 100.00,
    "fee": 4.00,              // max(2,50 ; valor×0,03+1,00)
    "netAmount": 96.00,
    "description": "Pedido #1234",
    "externalId": "order-456",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "pix": {
      "qrCode": "data:image/png;base64,...",  // imagem
      "copyPaste": "00020126...",              // copia-e-cola
      "expiresAt": "2025-01-01T00:30:00.000Z"
    }
  }
}

2.2 Consultar Transação

200 OK

curl "https://api.razepag.com/api/v1/pix/charge/TRANSACTION_ID" \
  -H "client_id: SEU_CLIENT_ID" \
  -H "client_secret: SEU_CLIENT_SECRET"

2.3 Consultar Saldo

200 OK

curl "https://api.razepag.com/api/v1/balance" \
  -H "client_id: SEU_CLIENT_ID" \
  -H "client_secret: SEU_CLIENT_SECRET"

{ "data": { "balance": 250.00, "pendingBalance": 12.50 } }

2.4 Listar Transações

200 OK

curl "https://api.razepag.com/api/v1/transactions?page=1&limit=20&status=PAID" \
  -H "client_id: SEU_CLIENT_ID" \
  -H "client_secret: SEU_CLIENT_SECRET"

{ "data": { "transactions": [...], "total": 42, "page": 1, "limit": 20, "totalPages": 3 } }

2.5 Transferência

Interna grátis

Por username (conta RazePag) — gratuita. Por pixKey (chave externa) — taxa normal.

# Transferência interna por @username (gratuita)
curl -X POST https://api.razepag.com/api/v1/transfer \
  -H "client_id: SEU_CLIENT_ID" \
  -H "client_secret: SEU_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"username": "joaosilva", "amount": 50.00}'

Gateway API (legado)

credenciais no body / query string

Credenciais enviadas no body JSON (POST) ou query string (GET). Mantido para compatibilidade. Para novas integrações, prefira a REST API v1.

Atenção — duplo /api no path

O prefixo global /api + o prefixo do controller /apiresultam em https://api.razepag.com/api/api/...

Base: https://api.razepag.com/api/api

POST/v1/c1/qrcode.phpGerar QR Code PIX

POST/v1/c1/payment.phpEnviar PIX para chave externa

GET/v1/c1/status.phpConsultar status de transação

GET/v2/account/balance.phpConsultar saldo

3.1 Gerar QR Code PIX

curl -X POST https://api.razepag.com/api/api/v1/c1/qrcode.php \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "SEU_CLIENT_ID",
    "client_secret": "SEU_CLIENT_SECRET",
    "valor": 100.00,
    "descricao": "Pedido #1234",
    "nome": "João Silva",
    "cpf": "123.456.789-00",
    "email": "joao@email.com",
    "external_id": "order-123"
  }'

Resposta — 200 OK

{
  "gateway": "razepag",
  "transactionId": "uuid-da-transacao",
  "external_id": "order-123",
  "status": "PENDING",
  "type": "RECEIVEPIX",
  "amount": 100.00,
  "tax": 4.00,
  "total": 96.00,            // valor líquido que você recebe
  "nome": "João Silva",
  "document": "123.456.789-00",
  "qrcode": "data:image/png;base64,...",
  "qrcode_text": "00020126...",
  "expires_at": "2025-01-01T00:30:00.000Z",
  "created_at": "2025-01-01T00:00:00.000Z"
}

3.2 Consultar Status

Query obrigatória: transaction_id (UUID interno) ou external_id (sua referência).

# Por transaction_id
curl "https://api.razepag.com/api/api/v1/c1/status.php?client_id=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET&transaction_id=UUID"

# Por external_id
curl "https://api.razepag.com/api/api/v1/c1/status.php?client_id=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET&external_id=order-123"

3.3 Consultar Saldo

curl "https://api.razepag.com/api/api/v2/account/balance.php?client_id=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET"

{ "gateway": "razepag", "balance": 250.00, "pending_balance": 0.00 }

Webhooks — Notificações de Pagamento

Quando um pagamento é confirmado, a RazePag envia um POST para o URL cadastrado no dashboard.

Como configurar

No Dashboard, acesse Webhooks → Novo endpoint. Configure a URL e os eventos desejados (payment.completed, payment.failed). Um secret HMAC-SHA256 é gerado para verificar a autenticidade dos eventos.

Payload do evento

payment.completed

// Payload enviado via POST para seu endpoint quando um pagamento é confirmado
{
  "event": "payment.completed",
  "gateway": "razepag",
  "transactionId": "uuid-da-transacao",
  "external_id": "order-123",       // sua referência original
  "status": "PAID",
  "type": "RECEIVEPIX",
  "amount": 100.00,                  // valor cobrado
  "tax": 4.00,                       // taxa RazePag
  "total": 96.00,                    // valor líquido creditado
  "created_at": "2025-01-01T00:00:00.000Z",
  "updated_at": "2025-01-01T00:01:30.000Z"
}

Evento	Quando é disparado
`payment.completed`	Pagamento PIX confirmado e saldo creditado
`payment.failed`	Pagamento expirado ou cancelado

Boas práticas

• Seu endpoint deve retornar HTTP 200 para confirmar o recebimento
• Sempre confirme o status via GET /api/v1/pix/charge/:id antes de liberar o pedido — não confie apenas no webhook
• Use o campo external_id para mapear ao pedido no seu sistema
• O sistema reenvia o webhook em caso de falha (retries automáticos)

Erros Comuns

Os erros mais frequentes relatados por desenvolvedores durante a integração.

404Esqueceu o /api na URL

✗ Errado

https://api.razepag.com/v1/pix/charge

✓ Correto

https://api.razepag.com/api/v1/pix/charge

O prefixo global /api é obrigatório em todos os endpoints.

404Gateway com /api simples em vez de duplo

✗ Errado

https://api.razepag.com/api/v1/c1/qrcode.php

✓ Correto

https://api.razepag.com/api/api/v1/c1/qrcode.php

O controller Gateway tem prefixo /api próprio somado ao global.

401Usando Authorization: Bearer

✗ Errado

Authorization: Bearer eyJhbGci...

✓ Correto

client_id: SEU_CLIENT_ID
client_secret: SEU_CLIENT_SECRET

A API não aceita JWT. Use client_id + client_secret nos headers.

401Usando x-api-key ou apikey

✗ Errado

x-api-key: SEU_CLIENT_SECRET

✓ Correto

client_id: SEU_ID
client_secret: SEU_SECRET

Os headers x-api-key e apikey não são reconhecidos pela API.

403IP não autorizado

✗ Errado

Requisição de IP fora da whitelist

✓ Correto

Adicione o IP no Dashboard → API → Credenciais

Se o whitelist de IPs está configurado, apenas IPs listados são aceitos.

400Faltando Content-Type em requisições POST

✗ Errado

curl -X POST ... -d '{"amount":100}'

✓ Correto

curl -X POST ... -H "Content-Type: application/json" -d '{"amount":100}'

O header Content-Type: application/json é obrigatório em todas as requisições com body.

Respostas de erro

HTTP	Causa	Campo message
400	Body inválido ou campo obrigatório ausente	`Descrição do campo com erro`
401	client_id / client_secret ausentes	`Credenciais ausentes.`
403	Credenciais inválidas ou IP bloqueado	`Credenciais inválidas ou IP não autorizado.`
404	Rota não existe (geralmente faltou /api)	`Cannot GET /...`
429	Rate limit atingido (60 req/min)	`ThrottlerException: Too Many Requests`
500	Erro interno (reportar ao suporte)	`Internal server error`

Status das Transações

Valores possíveis para o campo status em todas as respostas.

PENDING

Aguardando pagamento

PROCESSING

Processando no banco

PAID

Pago e confirmado

CANCELLED

Cancelado ou expirado

FAILED

Falha no processamento

Nota: O status PAID equivale ao que outros gateways chamam de COMPLETED. Não existe status COMPLETED na API da RazePag.

Taxas

Taxas aplicadas automaticamente. O campo fee na resposta mostra o valor exato cobrado.

Fórmula — PIX Recebido

taxa = max(2,50 ; valor × 0,03 + 1,00)

R$ 10,00-R$ 2,50= R$ 7,50

R$ 50,00-R$ 2,50= R$ 47,50

R$ 100,00-R$ 4,00= R$ 96,00

R$ 500,00-R$ 16,00= R$ 484,00

Resumo por tipo

PIX recebido3% + R$1,00 (mín. R$2,50)

Saque (PIX externo)R$3,49 fixo

Transferência internaGratuita

Problema na integração? Nosso suporte técnico está disponível.

Abrir suporte Criar conta