Gerar Cobrança PIX

Gere cobranças instantâneas via PIX, obtenha QR Codes e monitore o ciclo de vida dos pagamentos.

POST/charges

Descrição

Gera uma cobrança PIX instantânea e retorna os dados do QR Code para pagamento (payload Copia e Cola) juntamente com o ID da transação.

---

Parâmetros do Body

• amount number — Obrigatório O valor da cobrança em reais. Exemplo: 100.50

• description string — Obrigatório Descrição interna para a cobrança. Exemplo: "Pedido #1234"

• expiration number — Opcional Tempo de expiração do PIX em segundos. Padrão: 3600 (1 hora)

---

Resposta de Sucesso

Campo	Tipo	Descrição
id	string	ID único da cobrança — guarde este valor
amount	number	Valor em reais
description	string	Descrição informada
status	string	PENDING — aguardando pagamento
pix_code	string	Payload PIX Copia e Cola — use para gerar o QR Code
fee	number	Taxa descontada em reais
net_amount	number	Valor líquido que você recebe após a taxa
expires_at	string	Data/hora ISO 8601 de expiração
created_at	string	Data/hora ISO 8601 de criação

---

Códigos de Erro

Código	Motivo
400	amount ausente, zero ou negativo
400	description ausente ou vazia
401	Token inválido, ausente ou revogado
500	Erro interno ao criar cobrança — tente novamente

Requisição

curl -X POST https://api.nomadspay.com/charges \
  -H "Authorization: Bearer <SEU_CLIENT_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50,
    "description": "Pedido #1234",
    "expiration": 3600
  }'

Resposta (201 Created)

{
  "id": "A3F7C291",
  "amount": 100.50,
  "description": "Pedido #1234",
  "status": "PENDING",
  "pix_code": "00020126870014br.gov.bcb.pix...",
  "fee": 4.02,
  "net_amount": 96.48,
  "expires_at": "2024-01-01T13:00:00.000Z",
  "created_at": "2024-01-01T12:00:00Z"
}

Exemplo em JavaScript

const response = await fetch('https://api.nomadspay.com/charges', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.NOMADS_SECRET}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 100.50,
    description: 'Pedido #1234',
    expiration: 3600
  })
});

if (!response.ok) {
  const err = await response.json();
  throw new Error(`Erro ${response.status}: ${err.error}`);
}

const charge = await response.json();
// charge.id       → guarde para consultar status
// charge.pix_code → exiba como QR Code para o cliente
// charge.net_amount → valor líquido que você recebe

Exemplo em Python

import os, requests

secret = os.getenv("NOMADS_SECRET")

resp = requests.post(
    "https://api.nomadspay.com/charges",
    headers={
        "Authorization": f"Bearer {secret}",
        "Content-Type": "application/json"
    },
    json={
        "amount": 100.50,
        "description": "Pedido #1234",
        "expiration": 3600
    }
)

resp.raise_for_status()
charge = resp.json()

print(charge["id"])        # guarde este ID
print(charge["pix_code"])  # exiba como QR Code

---

Próximo Passo

Após criar a cobrança, exiba o pix_code como QR Code para o cliente. Quando o pagamento for confirmado, você receberá um webhook charge.paid na URL configurada no painel.

Use o id retornado para consultar o status da cobrança a qualquer momento.

---

❓ Dúvidas frequentes — Gerar Cobrança

Como saber se integrei corretamente?

Faça uma chamada de teste com "amount": 10.00 e verifique a resposta:

✅ Integração correta — você receberá:

• HTTP 201
• "status": "PENDING"
• "pix_code" começando com 000201 (padrão PIX do Banco Central)
• "net_amount" menor que "amount" (taxa descontada)
• "id" com código único

❌ Algo errado se vier:

• HTTP 401 → sua secret está incorreta (veja a pergunta sobre 401 abaixo)
• HTTP 400 → algum campo do body está faltando ou inválido
• "pix_code": null → problema no gateway — tente novamente ou contate o suporte

Como exibir o QR Code para o cliente?

O campo pix_code é o payload PIX padrão (Copia e Cola). Use qualquer biblioteca:

JavaScript / Node.js:

npm install qrcode

import QRCode from 'qrcode';
const imgBase64 = await QRCode.toDataURL(charge.pix_code);
// <img src={imgBase64} /> no React, ou envie como imagem na resposta

Python:

pip install qrcode pillow

import qrcode
img = qrcode.make(charge['pix_code'])
img.save('qrcode.png')

PHP:

composer require endroid/qr-code

use Endroid\QrCode\QrCode;
$qr = QrCode::create($charge['pix_code']);

Além do QR Code, sempre exiba o pix_code como texto para o cliente copiar e colar.

Recebi 401. O que fazer?

Checklist rápido:

1. O header está exatamente assim? → Authorization: Bearer np_secret_...
2. A secret foi copiada completa? Ela tem ~70 caracteres
3. Você está usando o client_secret, não o client_id?
4. A credencial está com status Ativa no painel? (app.nomadspay.com → API & Credenciais)
5. Há espaço ou quebra de linha extra na secret na variável de ambiente?

O pix_code veio null ou vazio. Por quê?

Isso indica falha no gateway ao gerar o QR Code. Causas possíveis:

• Gateway instável naquele momento (tente novamente em alguns segundos)
• Conta sem acquirer configurado (verifique em app.nomadspay.com → Configurações)

Se persistir após 3 tentativas, entre em contato com o suporte com o id da cobrança retornada.

Posso gerar várias cobranças ao mesmo tempo?

Sim. Não há limite de requisições concorrentes. Cada chamada retorna um id único — guarde todos para consulta posterior. Para volumes muito altos (mais de 100/segundo), use uma fila no seu backend para processar os webhooks de confirmação de forma ordenada.

O que acontece se o cliente não pagar dentro do prazo?

A cobrança fica com status: "PENDING" até o tempo definido em expiration. Após expirar, ao consultar o id o status retornará "EXPIRED". Não há cobrança de taxa para cobranças expiradas — apenas para pagamentos confirmados.

Como calcular o valor líquido antes de criar a cobrança?

Sua taxa está configurada no painel. Se for, por exemplo, 4% + R$ 0,00 fixo:

net_amount = amount - (amount × taxa_percentual / 100) - taxa_fixa

A resposta da API já retorna fee e net_amount calculados — use esses valores para exibir ao vendedor.

Preciso salvar o pix_code no meu banco de dados?

Recomendado salvar apenas o id. O pix_code pode ser recuperado a qualquer momento via GET /charges/:id. Salvar o id é suficiente para toda operação de consulta e reconciliação.

Posso definir um valor máximo por cobrança?

O limite máximo por cobrança é configurado pelo administrador da plataforma (campo max_ticket nas configurações da sua conta). Cobranças acima desse valor serão rejeitadas com 400. Entre em contato com o suporte para ajustar seu limite se necessário.