NomadsPay

Appearance

Integração com IA ​

Cole o Prompt Mestre abaixo em qualquer IA — ChatGPT, Claude, Gemini, Cursor, Copilot — e em segundos você terá o código de integração completo, pronto para gerar seu primeiro PIX.

Sem ler documentação. Sem configurar nada. Só colar e rodar.

📋 Prompt Mestre — Cole em qualquer IA ​

Como usar: copie todo o bloco abaixo, cole no chat da sua IA preferida, substitua SUA_SECRET_AQUI pela sua chave e diga qual linguagem você quer. A IA já vai gerar o código completo e até testar a conexão por você.

text
Você é um engenheiro sênior especialista em integrações de pagamento.

Preciso integrar o gateway NomadsPay no meu sistema.
Minha linguagem é: [INFORME SUA LINGUAGEM: Python / Node.js / PHP / C# / Java / etc.]
Minha secret key é: SUA_SECRET_AQUI

=== CONTRATO COMPLETO DA API NomadsPay ===

BASE URL: https://api.nomadspay.com
AUTENTICAÇÃO: Header  →  Authorization: Bearer <CLIENT_SECRET>
CONTENT-TYPE: application/json

--- ENDPOINTS DISPONÍVEIS ---

1. CRIAR COBRANÇA PIX
   Método: POST /charges
   Body:
     {
       "amount": number,          ← valor em reais (ex: 99.90)
       "description": string,     ← descrição da venda (ex: "Pedido #1234")
       "expiration": number       ← opcional, segundos até expirar (padrão: 3600)
     }
   Resposta 201:
     {
       "id": string,              ← ID único da cobrança (guarde este ID)
       "amount": number,
       "description": string,
       "status": "PENDING",
       "pix_code": string,        ← payload PIX Copia e Cola (exiba como QR Code)
       "fee": number,             ← taxa descontada
       "net_amount": number,      ← valor líquido que você recebe
       "expires_at": string       ← ISO 8601
     }

2. CONSULTAR STATUS DE UMA COBRANÇA
   Método: GET /charges/:id
   Resposta 200:
     {
       "id": string,
       "amount": number,
       "status": "PENDING" | "PAID" | "EXPIRED" | "CANCELLED",
       "pix_code": string,
       "e2e_id": string | null,   ← preenchido quando pago
       "paid_at": string | null,
       "payer_name": string | null,
       "payer_document": string | null
     }

3. LISTAR COBRANÇAS
   Método: GET /charges
   Query params opcionais: ?status=PAID&limit=50&offset=0
   Resposta 200: array de cobranças

4. SOLICITAR SAQUE (CASH-OUT PIX)
   Método: POST /withdrawals
   Headers Adicionais: Idempotency-Key: <uuid-gerado-na-hora>
   Body:
     {
       "amount": number,
       "pix_key_type": "CPF" | "CNPJ" | "EMAIL" | "TELEFONE" | "ALEATORIA",
       "pix_key": string
     }
   Resposta 201:
     {
       "id": string,
       "amount": number,
       "status": "PENDING",
       "queue_position": number
     }

5. WEBHOOK — RECEBER CONFIRMAÇÃO DE PAGAMENTO AUTOMATICAMENTE
   Configure sua URL de webhook no dashboard: app.nomadspay.com → Webhooks
   Quando um PIX for pago ou saque liquidado, a NomadsPay fará um POST na sua URL com:
     {
       "event": "charge.paid" | "withdrawal.paid" | "withdrawal.failed",
       "charge": {
         "id": string,
         "amount": number,
         "status": "PAID"
       },
       "timestamp": string
     }
   Cabeçalho de segurança enviado: X-Webhook-Secret: <SEU_WEBHOOK_SECRET>
   Sua URL deve responder HTTP 200. Qualquer outro código = reenvio automático.

=== REGRAS IMPORTANTES ===
- Sem chargeback. Sem reembolso automático. O que entrou é seu.
- O campo "pix_code" é o payload PIX padrão — use qualquer biblioteca de QR Code para exibir.
- Guarde sempre o "id" da cobrança para consultar o status.
- Para confirmar pagamento: consulte GET /charges/:id até status = "PAID",
  OU configure o webhook (recomendado — mais eficiente que polling).
- Erros comuns:
    401 → secret inválida ou ausente
    400 → amount ausente, zero ou negativo
    404 → ID de cobrança não encontrado
    500 → erro interno (tente novamente em alguns segundos)

=== O QUE PRECISO QUE VOCÊ FAÇA ===

1. Crie uma classe/serviço NomadsPay na minha linguagem com os métodos:
   - createCharge(amount, description, expiration?)  → retorna { id, pix_code, ... }
   - getCharge(id)                                   → retorna { status, e2e_id, ... }
   - listCharges(status?, limit?)                    → retorna array
   - requestWithdrawal(amount, pixKeyType, pixKey)   → retorna { id, status }

2. Crie um exemplo completo que:
   - Gera uma cobrança de R$ 10,00 de teste
   - Imprime o pix_code no terminal
   - Consulta o status após 5 segundos
   - Lida com erros corretamente

3. Crie um handler de webhook básico que:
   - Valida o X-Webhook-Secret
   - Lê os eventos "charge.paid" e "withdrawal.paid"
   - Imprime os dados do recebimento/saque

Use variáveis de ambiente para a secret. Adicione tipagem se a linguagem suportar.

✅ Como verificar se sua integração está correta ​

Após rodar o código gerado pela IA, confirme cada item:

1. Cobrança criada com sucesso? ​

A resposta do POST /charges deve conter:

  • "status": "PENDING" ✓
  • "pix_code" com uma string longa começando com 000201 ✓
  • "id" com um código único ✓
  • "net_amount" menor que "amount" (taxa descontada) ✓

2. Consulta de status funcionando? ​

Faça GET /charges/:id com o ID retornado. Deve retornar os mesmos dados da criação. Se receber 404, o ID está errado ou a secret usada é de outra conta.

3. Webhook recebendo corretamente? ​

Use o botão Testar Webhook no painel (app.nomadspay.com → Webhooks) para enviar um evento de teste para sua URL. Você deve:

  • Receber um POST na sua URL
  • O body deve conter "event": "charge.paid"
  • Seu servidor deve responder HTTP 200

4. Credencial correta? ​

Verifique se está usando a secret certa para o ambiente:

  • np_secret_... → produção (dinheiro real)
  • np_test_... (client_id de sandbox) → ambiente de testes

❓ Perguntas frequentes da integração ​

Como exibir o QR Code para o cliente?

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

JavaScript:

bash
npm install qrcode
javascript
import QRCode from 'qrcode';
const dataUrl = await QRCode.toDataURL(charge.pix_code);
// Use dataUrl como src de uma <img>

Python:

bash
pip install qrcode pillow
python
import qrcode
img = qrcode.make(charge['pix_code'])
img.save('qrcode.png')
Como saber quando o PIX foi pago sem ficar consultando todo segundo?

Configure um webhook. No dashboard (app.nomadspay.com → Webhooks), informe a URL do seu servidor. Quando o pagamento chegar, a NomadsPay fará um POST automático com os dados do pagamento — sem polling, sem delay.

Se precisar de polling (ex: apps sem servidor), consulte a cada 5-10 segundos por no máximo 30 minutos. Após isso, considere a cobrança expirada.

O que fazer se o pix_code vier vazio ou null?

Isso indica que o gateway teve um erro ao gerar o QR Code. Tente novamente. Se persistir, verifique se sua conta está com o acquirer configurado corretamente no painel (app.nomadspay.com → Configurações).

Posso usar a mesma secret em produção e sandbox?

Não. Cada ambiente tem credenciais separadas. Crie e gerencie suas credentials em app.nomadspay.com → API & Credenciais. Use variáveis de ambiente para trocar entre sandbox e produção sem alterar código.

Recebi 401. O que fazer?

Verifique:

  1. O header está exatamente como Authorization: Bearer np_secret_... (sem espaço extra, sem aspas)
  2. A secret foi copiada completa — ela é longa (~70 caracteres)
  3. A credential está com status Ativa no painel
  4. Você não está usando o client_id no lugar do client_secret — use sempre o client_secret
Posso criar cobranças em loop sem limite?

Sim, não há limite de cobranças por segundo na API. Para operações de alto volume (centenas por minuto), use filas no seu backend para evitar sobrecarga no seu próprio servidor ao processar os webhooks.

O cliente pagou, mas meu sistema não recebeu o webhook. O que fazer?
  1. Verifique os Logs de Webhook no painel — você verá todas as tentativas e os códigos de resposta
  2. Se o seu servidor retornou algo diferente de 200, a NomadsPay reencaminha automaticamente
  3. Como backup, faça GET /charges/:id periodicamente para reconciliar pagamentos perdidos
Como integrar com minha plataforma white label?

Cole o Prompt Mestre acima em qualquer IA e adicione ao final: "meu sistema é [NOME DA PLATAFORMA] e preciso que a integração siga o padrão de [descreva seu stack]". A IA vai adaptar o código para o seu contexto específico.

💡 Dica final ​

Se tiver qualquer dúvida durante a integração, cole o erro exato que está recebendo junto com o Prompt Mestre em qualquer IA. Com o contrato completo da API já no contexto, a IA vai diagnosticar e corrigir o problema na hora — sem precisar abrir um ticket.