Documentação

API de pagamentos Pix

Guia para integrar a criação e a consulta de cobranças Pix nas suas aplicações (sites e bots) usando o header x-api-key.

URL base (produção)

https://orbionwallet.online

Todas as rotas usam esse host + o caminho indicado (ex.: https://orbionwallet.online/api/v1/payments/create).

Obter a API Key

Faça login na sua conta da Orbion Wallet e acesse o Painel da API.
Clique em "Gerar chave" e dê um nome para identificá-la.
Guarde a chave com segurança — ela só é mostrada uma única vez, no momento da criação.

Gerar minha API Key

Autenticação

Em toda requisição, envie o header:

http

x-api-key: SUA_CHAVE_AQUI

Formato das respostas

Sucesso: o payload útil vem dentro de data.

json

{
  "success": true,
  "data": { ... }
}

Erro:

json

{
  "success": false,
  "error": "mensagem"
}

Validação (CPF inválido, valor fora do limite, etc.): HTTP 400, com lista em details.

json

{
  "success": false,
  "error": "Erro de validação",
  "details": [{ "field": "payerDocument", "message": "CPF do pagador inválido" }]
}

No seu código, use sempre response.data após verificar response.success === true.

1. Criar pagamento

POST/api/v1/payments/create

Campo	Tipo	Obrigatório	Observação
amount	number	Sim	Valor em reais, até 2 casas (ex.: 29.90). Mínimo R$ 5,00, máximo R$ 100.000.
payerName	string	Sim	3–100 caracteres.
payerDocument	string	Sim	CPF (com ou sem pontuação; a API normaliza).
description	string	Sim	1–200 caracteres.
externalId	string	Não	Até 100 caracteres — seu ID de pedido, assinatura, etc.

Exemplo (curl)

bash

curl -s -X POST "https://orbionwallet.online/api/v1/payments/create" \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_CHAVE_AQUI" \
  -d '{
    "amount": 29.90,
    "payerName": "João Silva",
    "payerDocument": "12345678900",
    "description": "Assinatura - Plano Pro",
    "externalId": "pedido-12345"
  }'

Resposta (HTTP 201)

json

{
  "success": true,
  "data": {
    "id": "1024",
    "externalId": "pedido-12345",
    "amount": 29.9,
    "pixCode": "00020126...",
    "qrCode": "data:image/png;base64,...",
    "status": "pending"
  }
}

data.id — use no GET para acompanhar o status.
data.pixCode — Pix copia e cola.
data.qrCode — QR em base64 (data URL) para exibir na tela.

2. Consultar pagamento

GET/api/v1/payments/:id

Substitua :id pelo id retornado em data.id ao criar.

Exemplo (curl)

bash

curl -s "https://orbionwallet.online/api/v1/payments/ID_DO_PAGAMENTO" \
  -H "x-api-key: SUA_CHAVE_AQUI"

Resposta (HTTP 200)

json

{
  "success": true,
  "data": {
    "id": "1024",
    "externalId": "pedido-12345",
    "amount": 29.9,
    "netAmount": 29.41,
    "status": "completed",
    "pixCode": "00020126...",
    "createdAt": "2026-02-25T12:00:00.000Z",
    "completedAt": "2026-02-25T12:05:00.000Z"
  }
}

Valores de status

status	Significado
pending	Aguardando pagamento
completed	Pago
expired	Expirado
cancelled	Cancelado

Fluxo sugerido no seu app

Chame POST /api/v1/payments/create com valor, nome, CPF, descrição e, se quiser, externalId.
Mostre o QR (data.qrCode) ou o Pix copia e cola (data.pixCode).
Faça polling com GET /api/v1/payments/:id a cada poucos segundos até data.status === "completed" (ou trate expired / cancelled).
Ao confirmar o pagamento, use o externalId (e/ou seu próprio banco) para liberar o produto ou acesso.

Segurança: nunca exponha a API Key no front-end público. Chame a Orbion sempre a partir do seu backend.

Erros frequentes

HTTP	Causa provável
401	API Key ausente, inválida ou revogada.
404	Pagamento inexistente ou de outra conta.
400	Body inválido (veja details).
502	Falha ao gerar a cobrança no provedor Pix.

Exemplo mínimo (Node / fetch)

javascript

const BASE = 'https://orbionwallet.online';
const API_KEY = process.env.ORBION_API_KEY;

async function criarPagamento() {
  const res = await fetch(`${BASE}/api/v1/payments/create`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify({
      amount: 10.5,
      payerName: 'Maria Souza',
      payerDocument: '52998224725',
      description: 'Teste de integração',
      externalId: 'meu-pedido-1',
    }),
  });
  const json = await res.json();
  if (!json.success) throw new Error(json.error || res.statusText);
  return json.data; // id, pixCode, qrCode, status, ...
}

async function statusPagamento(id) {
  const res = await fetch(`${BASE}/api/v1/payments/${id}`, {
    headers: { 'x-api-key': API_KEY },
  });
  const json = await res.json();
  if (!json.success) throw new Error(json.error || res.statusText);
  return json.data;
}