orbpag
Entrar

API v1

Documentação da API OrbPag

A API REST da OrbPag permite criar cobranças PIX, acompanhar pagamentos, solicitar saques em PIX ou USDT, consultar o saldo, acompanhar infrações MED e receber notificações em tempo real por webhooks assinados.

Todas as requisições e respostas usam JSON sobre HTTPS. A URL base de todos os endpoints é:

https://api.orbpag.com/v1

Autenticação

Use sua chave secreta no cabeçalho Authorization.

Primeira cobrança

Gere um QR Code PIX em uma chamada.

Webhooks

Receba a confirmação do pagamento em segundos.

Autenticação

Autentique cada requisição com uma chave secreta no cabeçalho Authorization: Bearer sk_live_SUA_CHAVE_SECRETA. As chaves são criadas no painel em Desenvolvedores › Chaves de API e o valor completo é exibido uma única vez, no momento da criação.

A chave dá acesso total à conta via API: guarde-a em uma variável de ambiente do seu servidor e nunca a exponha em aplicativos, páginas web ou repositórios. Se uma chave vazar, revogue-a no painel — o efeito é imediato.

Exemplo
curl https://api.orbpag.com/v1/balance \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA"

Erros de autenticação

Sem o cabeçalho, a API responde 401 com o código missing_api_key. Chaves inexistentes ou revogadas retornam 401 com invalid_api_key.

Ambiente de testes

Cada conta opera em um ambiente, indicado por um selo no topo do painel: Sandbox (testes) ou Produção. Os endpoints, o formato das chaves e os objetos são idênticos nos dois ambientes — o que muda é que, no Sandbox, as cobranças geram QR Codes de teste e nenhum valor real é movimentado.

Valide sua integração de ponta a ponta no Sandbox: crie cobranças, consulte o status e use o botão Enviar teste em Desenvolvedores › Webhooks para receber um evento assinado no seu endpoint. Eventos de teste trazem data.test = true.

SandboxProdução

Convenções

TemaRegra
ValoresSempre inteiros em centavos de real: R$ 159,90 é 15990. Quantidades de USDT são decimais (ex.: 183.42).
IdentificadoresStrings com prefixo por tipo: pay_ cobrança, wdr_ saque, dsp_ infração, evt_ evento, cus_ cliente, req_ requisição.
DatasISO 8601 em UTC, ex.: 2026-09-29T14:32:10.000Z.
CamposNomes em camelCase. Campos sem valor são retornados como null.
Tipo do objetoTodo objeto traz o campo object (charge, withdrawal, dispute, list…).
metadataAté 20 chaves (máx. 40 caracteres) com valores string (até 500 caracteres), número ou booleano. Devolvido como enviado.
RastreioToda resposta traz o cabeçalho X-Request-Id. Informe-o ao suporte ao relatar um problema.

Erros

Erros usam códigos HTTP convencionais e um corpo padronizado. Use code para tratar o erro no seu sistema e message (em português) para exibir ou registrar. Em erros de validação, details lista os campos inválidos.

422 · Corpo do erro
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "Um ou mais campos são inválidos.",
    "details": [
      {
        "field": "customer.document",
        "message": "CPF ou CNPJ inválido"
      }
    ],
    "requestId": "req_1k3ncn44p2k6s0v4y8b3e7h1mg"
  }
}
HTTPQuando aconteceCódigos comuns
400JSON malformado ou regra de negócio violada.invalid_json amount_too_small invalid_pix_key
401Chave ausente, inválida ou revogada.missing_api_key invalid_api_key
403Conta ainda não habilitada para transacionar.merchant_not_active kyc_pending
404Recurso inexistente ou de outra conta.not_found
409Conflito com o estado atual do recurso.idempotency_conflict duplicate_reference insufficient_balance already_refunded
422Campos inválidos ou operação recusada pelo liquidante.validation_error processor_declined
429Limite de requisições excedido.rate_limited
500Erro inesperado da OrbPag.internal_error
502Liquidante indisponível ou sem resposta. Operações registradas são reprocessadas.processor_error processor_unavailable
503Recebimentos e saques ainda não habilitados na plataforma. Nada é registrado.processor_not_configured

O campo type agrupa os erros em invalid_request_error, authentication_error, rate_limit_error, processor_error e api_error.

Idempotência

Envie o cabeçalho Idempotency-Key em POST /charges e POST /withdrawals para repetir uma requisição com segurança (por exemplo, após um timeout). Se a chave já foi usada, a API devolve o objeto criado originalmente em vez de criar outro.

Use um valor único por operação — o ID do pedido ou um UUID — com até 200 caracteres. Reutilizar a mesma chave em uma cobrança com valor diferente retorna 409 idempotency_conflict.

Cabeçalho
-H "Idempotency-Key: 9f1c2a4e-7b1d-4c55-9a0e-2f8d6c3b7e10"

Paginação

As listagens retornam os itens mais recentes primeiro, no formato { "object": "list", "data": [...], "hasMore": true }. Para buscar a próxima página, envie em startingAfter o id do último item recebido enquanto hasMore for true.

Parâmetros de consulta

limitintegeropcional
Itens por página, de 1 a 100. Padrão: 20.
startingAfterstringopcional
ID do último item da página anterior. Retorna os itens criados antes dele.
cURL
# Página seguinte: passe o id do último item recebido
curl "https://api.orbpag.com/v1/charges?limit=50&startingAfter=pay_1k3ncn44q7xm2d9fr4t8wz6hya" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA"

Recursos

Cobranças

Uma cobrança representa um pagamento PIX. Ao criá-la, você recebe o código copia e cola, o QR Code e um link de checkout. Quando o pagador conclui o PIX, a cobrança passa para paid e enviamos o evento charge.paid. Cobranças não pagas expiram no horário indicado em expiresAt e geram o evento charge.expired.

O objeto cobrança

idstring
Identificador com prefixo pay_.
statusenum
pending (aguardando pagamento), paid, expired, canceled, refunded ou failed.
amountinteger
Valor da cobrança em centavos.
feeinteger
Tarifa cobrada da sua conta, em centavos.
netAmountinteger
Valor líquido creditado no saldo após o pagamento (amount − fee).
customerobject
Dados do pagador: id, name, email, phone (E.164) e document (somente dígitos).
productId · offerIdstring | null
Produto e oferta quando a cobrança veio do checkout de um produto. Use para liberar o acesso certo ao comprador.
pix.copyPastestring
Código PIX copia e cola (BR Code). Exiba para o pagador junto com o QR Code.
pix.qrCodeImagestring
Imagem do QR Code (data URL PNG).
checkoutUrlstring
Página de pagamento hospedada pela OrbPag, pronta para compartilhar.
refundobject
Estado do estorno: none, requested, refunded ou failed.
settlementobject
usdt indica liquidação em USDT; withdrawalId aponta o saque on-chain gerado.
expiresAt · paidAtstring | null
Datas ISO 8601 (UTC) de expiração e de confirmação do pagamento.
POST/v1/charges

Criar cobrança

Cria uma cobrança PIX e retorna 201 com o objeto cobrança. Aceita Idempotency-Key. Valores entre R$ 1,00 e R$ 100.000,00.

Corpo da requisição

amountintegerobrigatório
Valor em centavos. Ex.: 15990 = R$ 159,90.
customerobjectobrigatório
Pagador: name (3–120 caracteres), email, phone (DDD + número) e document (CPF ou CNPJ válido).
descriptionstringopcional
Descrição exibida ao pagador (até 200 caracteres).
externalReferencestringopcional
Identificador do pedido no seu sistema (até 100 caracteres). Único por conta: repetições retornam 409.
metadataobjectopcional
Pares chave-valor livres, devolvidos na cobrança e nos webhooks.
settlement"brl" | "usdt"opcional
Padrão brl. Com usdt, o valor líquido é convertido e enviado on-chain para a carteira cadastrada em Configurações › Liquidação.

Cabeçalhos

Idempotency-Keystringopcional
Evita cobranças duplicadas em novas tentativas.
Requisição
curl -X POST https://api.orbpag.com/v1/charges \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042" \
  -d '{
    "amount": 15990,
    "description": "Pedido #1042",
    "externalReference": "pedido-1042",
    "customer": {
      "name": "Maria Oliveira",
      "email": "maria@exemplo.com.br",
      "phone": "11987654321",
      "document": "12345678909"
    },
    "metadata": { "orderId": "1042" },
    "settlement": "brl"
  }'
201 · Resposta
{
  "id": "pay_1k3ncn44q7xm2d9fr4t8wz6hya",
  "object": "charge",
  "status": "pending",
  "amount": 15990,
  "fee": 368,
  "netAmount": 15622,
  "currency": "BRL",
  "method": "pix",
  "description": "Pedido #1042",
  "externalReference": "pedido-1042",
  "metadata": {
    "orderId": "1042"
  },
  "productId": null,
  "offerId": null,
  "customer": {
    "id": "cus_1k3nbp20e5vq8k3m7c1xd9gt2b",
    "name": "Maria Oliveira",
    "email": "maria@exemplo.com.br",
    "phone": "+5511987654321",
    "document": "12345678909"
  },
  "pix": {
    "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/cobv/9d36b84f…6304A1B2",
    "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…"
  },
  "checkoutUrl": "https://orbpag.com/pay/pay_1k3ncn44q7xm2d9fr4t8wz6hya",
  "paymentLinkId": null,
  "source": "api",
  "refund": {
    "status": "none",
    "requestedAt": null,
    "refundedAt": null,
    "failureReason": null
  },
  "settlement": {
    "usdt": false,
    "withdrawalId": null
  },
  "expiresAt": "2026-09-29T15:02:10.000Z",
  "paidAt": null,
  "createdAt": "2026-09-29T14:32:10.000Z",
  "updatedAt": "2026-09-29T14:32:10.000Z"
}
GET/v1/charges

Listar cobranças

Retorna as cobranças da conta, das mais recentes para as mais antigas.

Parâmetros de consulta

limitintegeropcional
Itens por página, de 1 a 100. Padrão: 20.
startingAfterstringopcional
ID do último item da página anterior. Retorna os itens criados antes dele.
statusenumopcional
Filtra por status: pending, paid, expired, canceled, refunded ou failed.
externalReferencestringopcional
Busca a cobrança pela referência do seu sistema.
Requisição
curl "https://api.orbpag.com/v1/charges?status=paid&limit=20" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA"
Resposta
{
  "object": "list",
  "data": [
    {
      "id": "pay_1k3ncn44q7xm2d9fr4t8wz6hya",
      "object": "charge",
      "status": "paid",
      "amount": 15990,
      "fee": 368,
      "netAmount": 15622,
      "currency": "BRL",
      "method": "pix",
      "description": "Pedido #1042",
      "externalReference": "pedido-1042",
      "metadata": {
        "orderId": "1042"
      },
      "productId": null,
      "offerId": null,
      "customer": {
        "id": "cus_1k3nbp20e5vq8k3m7c1xd9gt2b",
        "name": "Maria Oliveira",
        "email": "maria@exemplo.com.br",
        "phone": "+5511987654321",
        "document": "12345678909"
      },
      "pix": {
        "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/cobv/9d36b84f…6304A1B2",
        "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…"
      },
      "checkoutUrl": "https://orbpag.com/pay/pay_1k3ncn44q7xm2d9fr4t8wz6hya",
      "paymentLinkId": null,
      "source": "api",
      "refund": {
        "status": "none",
        "requestedAt": null,
        "refundedAt": null,
        "failureReason": null
      },
      "settlement": {
        "usdt": false,
        "withdrawalId": null
      },
      "expiresAt": "2026-09-29T15:02:10.000Z",
      "paidAt": "2026-09-29T14:33:42.000Z",
      "createdAt": "2026-09-29T14:32:10.000Z",
      "updatedAt": "2026-09-29T14:33:42.000Z"
    }
  ],
  "hasMore": false
}
GET/v1/charges/{id}

Consultar cobrança

Retorna uma cobrança pelo ID. Use como fonte da verdade ao reconciliar pedidos ou após receber um webhook.

Parâmetros de caminho

idstringobrigatório
ID da cobrança (pay_…).
Requisição
curl https://api.orbpag.com/v1/charges/pay_1k3ncn44q7xm2d9fr4t8wz6hya \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA"
Resposta
{
  "id": "pay_1k3ncn44q7xm2d9fr4t8wz6hya",
  "object": "charge",
  "status": "paid",
  "amount": 15990,
  "fee": 368,
  "netAmount": 15622,
  "currency": "BRL",
  "method": "pix",
  "description": "Pedido #1042",
  "externalReference": "pedido-1042",
  "metadata": {
    "orderId": "1042"
  },
  "productId": null,
  "offerId": null,
  "customer": {
    "id": "cus_1k3nbp20e5vq8k3m7c1xd9gt2b",
    "name": "Maria Oliveira",
    "email": "maria@exemplo.com.br",
    "phone": "+5511987654321",
    "document": "12345678909"
  },
  "pix": {
    "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/cobv/9d36b84f…6304A1B2",
    "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…"
  },
  "checkoutUrl": "https://orbpag.com/pay/pay_1k3ncn44q7xm2d9fr4t8wz6hya",
  "paymentLinkId": null,
  "source": "api",
  "refund": {
    "status": "none",
    "requestedAt": null,
    "refundedAt": null,
    "failureReason": null
  },
  "settlement": {
    "usdt": false,
    "withdrawalId": null
  },
  "expiresAt": "2026-09-29T15:02:10.000Z",
  "paidAt": "2026-09-29T14:33:42.000Z",
  "createdAt": "2026-09-29T14:32:10.000Z",
  "updatedAt": "2026-09-29T14:33:42.000Z"
}
POST/v1/charges/{id}/refund

Estornar cobrança

Solicita o estorno integral de uma cobrança paga e retorna 200 com refund.status = "requested". A confirmação chega pelo evento charge.refunded.

Retorna 409 se a cobrança não estiver paga, já tiver sido estornada, tiver um estorno em andamento ou uma infração MED aberta.

Parâmetros de caminho

idstringobrigatório
ID da cobrança (pay_…).
Requisição
curl -X POST https://api.orbpag.com/v1/charges/pay_1k3ncn44q7xm2d9fr4t8wz6hya/refund \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA"
Resposta
{
  "id": "pay_1k3ncn44q7xm2d9fr4t8wz6hya",
  "object": "charge",
  "status": "paid",
  "amount": 15990,
  "fee": 368,
  "netAmount": 15622,
  "currency": "BRL",
  "method": "pix",
  "description": "Pedido #1042",
  "externalReference": "pedido-1042",
  "metadata": {
    "orderId": "1042"
  },
  "productId": null,
  "offerId": null,
  "customer": {
    "id": "cus_1k3nbp20e5vq8k3m7c1xd9gt2b",
    "name": "Maria Oliveira",
    "email": "maria@exemplo.com.br",
    "phone": "+5511987654321",
    "document": "12345678909"
  },
  "pix": {
    "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/cobv/9d36b84f…6304A1B2",
    "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…"
  },
  "checkoutUrl": "https://orbpag.com/pay/pay_1k3ncn44q7xm2d9fr4t8wz6hya",
  "paymentLinkId": null,
  "source": "api",
  "refund": {
    "status": "requested",
    "requestedAt": "2026-09-30T10:05:00.000Z",
    "refundedAt": null,
    "failureReason": null
  },
  "settlement": {
    "usdt": false,
    "withdrawalId": null
  },
  "expiresAt": "2026-09-29T15:02:10.000Z",
  "paidAt": "2026-09-29T14:33:42.000Z",
  "createdAt": "2026-09-29T14:32:10.000Z",
  "updatedAt": "2026-09-30T10:05:00.000Z"
}

Saques

Saques transferem saldo disponível para uma chave PIX (sua ou de terceiros) ou para uma carteira USDT. O valor mais a tarifa é debitado na criação; se o saque falhar, o total volta ao saldo e enviamos withdrawal.failed. Status: pending, processing, paid, failed e canceled.

POST/v1/withdrawals

Criar saque

Escolha o tipo com method: "pix" ou "usdt". Retorna 201 com o objeto saque. Aceita Idempotency-Key. Valor mínimo: R$ 10,00. Saldo insuficiente retorna 409 insufficient_balance.

Corpo · method "pix"

method"pix"obrigatório
Saque via PIX.
amountintegerobrigatório
Valor enviado, em centavos. A tarifa de saque é debitada à parte.
pixKeystringobrigatório
Chave PIX de destino: CPF, CNPJ, e-mail, telefone (+55…) ou chave aleatória.
recipientobjectopcional
Titular da chave: name, document, email e phone opcionais. Se omitido, o destinatário é a sua própria empresa.
strictbooleanopcional
Padrão true: o saque só é concluído se a chave pertencer ao documento do destinatário.
externalReferencestringopcional
Identificador no seu sistema (até 100 caracteres).
metadataobjectopcional
Pares chave-valor livres.

Corpo · method "usdt"

method"usdt"obrigatório
Conversão para USDT e envio on-chain.
amountintegerobrigatório
Valor em reais a converter, em centavos.
networkenumobrigatório
Rede: trx (TRC-20), eth (ERC-20), matic (Polygon), ton (TON).
addressstringobrigatório
Endereço da carteira, válido para a rede escolhida.
externalReferencestringopcional
Identificador no seu sistema.
metadataobjectopcional
Pares chave-valor livres.

Transferências on-chain são irreversíveis

Confira a rede e o endereço antes de enviar. USDT enviado para a rede errada ou para um endereço incorreto não pode ser recuperado.

Exemplos adicionais

PIX para terceiros
curl -X POST https://api.orbpag.com/v1/withdrawals \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pix",
    "amount": 25000,
    "pixKey": "98765432100",
    "recipient": {
      "name": "João Fornecedor",
      "document": "98765432100"
    },
    "strict": true
  }'
Saque em USDT
curl -X POST https://api.orbpag.com/v1/withdrawals \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: usdt-0929" \
  -d '{
    "method": "usdt",
    "amount": 100000,
    "network": "trx",
    "address": "TXcY6oJ3mV5k2WqzQh8n4Rr7sLpDdE9uFa"
  }'
201 · Resposta (USDT)
{
  "id": "wdr_1k3ncv02h7t1b5x9e3q6jn8wkd",
  "object": "withdrawal",
  "method": "usdt",
  "status": "processing",
  "amount": 100000,
  "fee": 1000,
  "totalDebit": 101000,
  "currency": "BRL",
  "pix": null,
  "usdt": {
    "network": "trx",
    "address": "TXcY6oJ3mV5k2WqzQh8n4Rr7sLpDdE9uFa",
    "amount": 183.42,
    "price": 5.4521
  },
  "failureReason": null,
  "externalReference": null,
  "metadata": {},
  "source": "api",
  "paymentId": null,
  "completedAt": null,
  "createdAt": "2026-09-29T14:32:10.000Z",
  "updatedAt": "2026-09-29T14:32:10.000Z"
}
Requisição
curl -X POST https://api.orbpag.com/v1/withdrawals \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: repasse-0921" \
  -d '{
    "method": "pix",
    "amount": 50000,
    "pixKey": "financeiro@minhaloja.com.br",
    "externalReference": "repasse-0921"
  }'
201 · Resposta
{
  "id": "wdr_1k3ncs81w3p9z6r2m4k8qf5dnc",
  "object": "withdrawal",
  "method": "pix",
  "status": "pending",
  "amount": 50000,
  "fee": 200,
  "totalDebit": 50200,
  "currency": "BRL",
  "pix": {
    "key": "financeiro@minhaloja.com.br",
    "recipientName": "Minha Loja LTDA",
    "recipientDocument": "11222333000181",
    "strict": true
  },
  "usdt": null,
  "failureReason": null,
  "externalReference": "repasse-0921",
  "metadata": {},
  "source": "api",
  "paymentId": null,
  "completedAt": null,
  "createdAt": "2026-09-29T14:32:10.000Z",
  "updatedAt": "2026-09-29T14:32:10.000Z"
}
GET/v1/withdrawals

Listar saques

Retorna os saques da conta, dos mais recentes para os mais antigos, incluindo as liquidações automáticas em USDT.

Parâmetros de consulta

limitintegeropcional
Itens por página, de 1 a 100. Padrão: 20.
startingAfterstringopcional
ID do último item da página anterior. Retorna os itens criados antes dele.
statusenumopcional
Filtra por pending, processing, paid, failed ou canceled.
Requisição
curl "https://api.orbpag.com/v1/withdrawals?limit=20" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA"
Resposta
{
  "object": "list",
  "data": [
    {
      "id": "wdr_1k3ncs81w3p9z6r2m4k8qf5dnc",
      "object": "withdrawal",
      "method": "pix",
      "status": "pending",
      "amount": 50000,
      "fee": 200,
      "totalDebit": 50200,
      "currency": "BRL",
      "pix": {
        "key": "financeiro@minhaloja.com.br",
        "recipientName": "Minha Loja LTDA",
        "recipientDocument": "11222333000181",
        "strict": true
      },
      "usdt": null,
      "failureReason": null,
      "externalReference": "repasse-0921",
      "metadata": {},
      "source": "api",
      "paymentId": null,
      "completedAt": null,
      "createdAt": "2026-09-29T14:32:10.000Z",
      "updatedAt": "2026-09-29T14:32:10.000Z"
    }
  ],
  "hasMore": false
}
GET/v1/withdrawals/{id}

Consultar saque

Retorna um saque pelo ID.

Parâmetros de caminho

idstringobrigatório
ID do saque (wdr_…).
Requisição
curl https://api.orbpag.com/v1/withdrawals/wdr_1k3ncs81w3p9z6r2m4k8qf5dnc \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA"
Resposta
{
  "id": "wdr_1k3ncs81w3p9z6r2m4k8qf5dnc",
  "object": "withdrawal",
  "method": "pix",
  "status": "pending",
  "amount": 50000,
  "fee": 200,
  "totalDebit": 50200,
  "currency": "BRL",
  "pix": {
    "key": "financeiro@minhaloja.com.br",
    "recipientName": "Minha Loja LTDA",
    "recipientDocument": "11222333000181",
    "strict": true
  },
  "usdt": null,
  "failureReason": null,
  "externalReference": "repasse-0921",
  "metadata": {},
  "source": "api",
  "paymentId": null,
  "completedAt": null,
  "createdAt": "2026-09-29T14:32:10.000Z",
  "updatedAt": "2026-09-29T14:32:10.000Z"
}

Saldo

GET/v1/balance

Consultar saldo

Retorna o saldo em centavos: available pode ser sacado, blocked está retido por infrações MED em análise e total é a soma dos dois.

Requisição
curl https://api.orbpag.com/v1/balance \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA"
Resposta
{
  "object": "balance",
  "currency": "BRL",
  "available": 1284350,
  "blocked": 15990,
  "total": 1300340
}

Cotação USDT

GET/v1/usdt/quote

Cotar conversão

Simula a conversão de reais para USDT antes de criar um saque. A cotação é indicativa: o valor final é definido no momento da execução. Valores em centavos; usdtAmount em USDT e price em reais por USDT.

Parâmetros de consulta

amountintegerobrigatório
Valor em reais a converter, em centavos.
networkenumopcional
Rede de destino: trx (TRC-20), eth (ERC-20), matic (Polygon), ton (TON).
addressstringopcional
Endereço de destino, para incluir custos de envio na cotação.
Requisição
curl "https://api.orbpag.com/v1/usdt/quote?amount=100000&network=trx" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA"
Resposta
{
  "object": "usdt_quote",
  "amountCents": 100000,
  "platformFeeCents": 1000,
  "totalDebitCents": 101000,
  "processorFeeCents": 0,
  "usdtAmount": 183.42,
  "price": 5.4521
}

Infrações MED

Infrações do Mecanismo Especial de Devolução (MED) são abertas quando o pagador contesta um PIX. O valor fica bloqueado no saldo até a conclusão da análise. Status: pending (aguardando defesa), analysis, canceled (encerrada a seu favor) e refunded (devolvida ao pagador). A defesa é enviada pelo painel, em Infrações MED.

GET/v1/disputes

Listar infrações

Retorna as infrações vinculadas às suas cobranças.

Parâmetros de consulta

limitintegeropcional
Itens por página, de 1 a 100. Padrão: 20.
startingAfterstringopcional
ID do último item da página anterior. Retorna os itens criados antes dele.
statusenumopcional
Filtra por pending, analysis, canceled ou refunded.
Requisição
curl "https://api.orbpag.com/v1/disputes?status=pending" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA"
Resposta
{
  "object": "list",
  "data": [
    {
      "id": "dsp_1k3nd1c5m8r2w6y4t9p3vb7kze",
      "object": "dispute",
      "status": "pending",
      "amount": 15990,
      "chargeId": "pay_1k3ncn44q7xm2d9fr4t8wz6hya",
      "reason": "fraud",
      "description": "Pagador alega não reconhecer a transação.",
      "endToEndId": "E18236120202609291433s0123456789",
      "deadlineAt": "2026-10-06T14:33:42.000Z",
      "appealedAt": null,
      "resolvedAt": null,
      "createdAt": "2026-09-30T09:12:00.000Z",
      "updatedAt": "2026-09-30T09:12:00.000Z"
    }
  ],
  "hasMore": false
}
GET/v1/disputes/{id}

Consultar infração

Retorna uma infração pelo ID, com o prazo de defesa em deadlineAt.

Parâmetros de caminho

idstringobrigatório
ID da infração (dsp_…).
Requisição
curl https://api.orbpag.com/v1/disputes/dsp_1k3nd1c5m8r2w6y4t9p3vb7kze \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA"
Resposta
{
  "id": "dsp_1k3nd1c5m8r2w6y4t9p3vb7kze",
  "object": "dispute",
  "status": "pending",
  "amount": 15990,
  "chargeId": "pay_1k3ncn44q7xm2d9fr4t8wz6hya",
  "reason": "fraud",
  "description": "Pagador alega não reconhecer a transação.",
  "endToEndId": "E18236120202609291433s0123456789",
  "deadlineAt": "2026-10-06T14:33:42.000Z",
  "appealedAt": null,
  "resolvedAt": null,
  "createdAt": "2026-09-30T09:12:00.000Z",
  "updatedAt": "2026-09-30T09:12:00.000Z"
}

Integração

Webhooks

Cadastre endpoints HTTPS em Desenvolvedores › Webhooks e escolha os eventos. A cada mudança relevante enviamos um POST com o evento em JSON, assinado com o segredo do endpoint (whsec_…).

Eventos

EventoQuandodata
charge.createdCobrança criada e QR Code disponívelCobrança
charge.paidPagamento confirmadoCobrança
charge.expiredCobrança expirou sem pagamentoCobrança
charge.canceledCobrança canceladaCobrança
charge.refundedEstorno concluídoCobrança
withdrawal.createdSaque solicitadoSaque
withdrawal.processingSaque em processamentoSaque
withdrawal.paidSaque concluídoSaque
withdrawal.failedSaque falhou ou foi cancelado (valor devolvido)Saque
dispute.openedNova infração MEDInfração
dispute.updatedInfração em análiseInfração
dispute.wonInfração encerrada a favor do lojistaInfração
dispute.lostInfração devolvida ao pagadorInfração

Formato do evento

O corpo é um envelope com id, object: "event", type, createdAt e data — o objeto completo no momento do evento, no mesmo formato da API.

Corpo · charge.paid
{
  "id": "evt_1k3ncn9x0f4j8m2q6t1w5z3hcf",
  "object": "event",
  "type": "charge.paid",
  "createdAt": "2026-09-29T14:33:42.000Z",
  "data": {
    "id": "pay_1k3ncn44q7xm2d9fr4t8wz6hya",
    "object": "charge",
    "status": "paid",
    "amount": 15990,
    "fee": 368,
    "netAmount": 15622,
    "currency": "BRL",
    "method": "pix",
    "description": "Pedido #1042",
    "externalReference": "pedido-1042",
    "metadata": {
      "orderId": "1042"
    },
    "productId": null,
    "offerId": null,
    "customer": {
      "id": "cus_1k3nbp20e5vq8k3m7c1xd9gt2b",
      "name": "Maria Oliveira",
      "email": "maria@exemplo.com.br",
      "phone": "+5511987654321",
      "document": "12345678909"
    },
    "pix": {
      "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/cobv/9d36b84f…6304A1B2",
      "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…"
    },
    "checkoutUrl": "https://orbpag.com/pay/pay_1k3ncn44q7xm2d9fr4t8wz6hya",
    "paymentLinkId": null,
    "source": "api",
    "refund": {
      "status": "none",
      "requestedAt": null,
      "refundedAt": null,
      "failureReason": null
    },
    "settlement": {
      "usdt": false,
      "withdrawalId": null
    },
    "expiresAt": "2026-09-29T15:02:10.000Z",
    "paidAt": "2026-09-29T14:33:42.000Z",
    "createdAt": "2026-09-29T14:32:10.000Z",
    "updatedAt": "2026-09-29T14:33:42.000Z"
  }
}

Cabeçalhos

Requisição recebida
POST /webhooks/orbpag
Content-Type: application/json
User-Agent: OrbPag-Webhooks/1.0
OrbPag-Event-Id: evt_1k3ncn9x0f4j8m2q6t1w5z3hcf
OrbPag-Event-Type: charge.paid
OrbPag-Signature: t=1790692422,v1=5f0c1e9a4b…
CabeçalhoConteúdo
OrbPag-SignatureAssinatura no formato t=<unix>,v1=<hex>.
OrbPag-Event-IdID do evento (evt_…). Use para descartar duplicatas.
OrbPag-Event-TypeTipo do evento, igual ao campo type do corpo.

Verificando a assinatura

Calcule HMAC-SHA256(segredo, `${t}.${corpo}`) em hexadecimal sobre o corpo bruto da requisição e compare com v1 em tempo constante. Rejeite eventos com t mais antigo que 5 minutos para evitar replays.

Node.js (Express)
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.ORBPAG_WEBHOOK_SECRET; // whsec_…
const TOLERANCE_SECONDS = 5 * 60; // rejeita assinaturas com mais de 5 minutos

function verifySignature(rawBody, header, secret) {
  // Cabeçalho: OrbPag-Signature: t=<unix>,v1=<hex>
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Use o corpo BRUTO da requisição: qualquer reserialização invalida a assinatura.
app.post("/webhooks/orbpag", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body.toString("utf8");
  if (!verifySignature(rawBody, req.get("OrbPag-Signature") ?? "", SECRET)) {
    return res.status(400).send("Assinatura inválida");
  }

  const event = JSON.parse(rawBody);
  // Idempotência: ignore eventos já processados (event.id = OrbPag-Event-Id).
  switch (event.type) {
    case "charge.paid":
      // libere o pedido event.data.externalReference
      break;
    case "withdrawal.failed":
      // o valor já voltou para o seu saldo
      break;
  }

  res.sendStatus(200); // responda 2xx em até 10 segundos
});

Entrega e novas tentativas

  • Responda com um status 2xx em até 10 segundos. Processe tarefas demoradas de forma assíncrona.
  • Falhas (status diferente de 2xx, timeout ou erro de rede) são reenviadas após 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h. Depois disso, a entrega é marcada como falha e pode ser reenviada manualmente no painel.
  • Redirecionamentos não são seguidos. Em produção, apenas URLs HTTPS públicas são aceitas.
  • A entrega é "pelo menos uma vez" e a ordem não é garantida: deduplique pelo id do evento e, em caso de dúvida, consulte o recurso pela API.

Limites

LimiteValor
Requisições por chave de API300 por minuto. Acima disso: 429 rate_limited.
Chaves de API ativas10 por conta
Endpoints de webhook10 por conta
Itens por página100 (padrão 20)
Valor por cobrançaR$ 1,00 a R$ 100.000,00
Saque mínimoR$ 10,00
Ao receber 429, aguarde alguns segundos e tente novamente com backoff exponencial. Precisa de limites maiores? Fale com o suporte.