API de Pagamentos

Bem-vindo à documentação da API OrbePay. Integre PIX, consulte transações, faça split entre até 10 contas e gerencie cashouts com as credenciais do painel.

Obter credenciais

Início rápido

Complete o KYC no painel e aguarde a aprovação.
Gere o API Secret em Integrações → API.
Envie o header api-secret em todas as chamadas.
Configure um webhook para receber mudanças de status.

URL Base da API

Todas as requisições vão para:

https://app.orbepay.vip/api

Os endpoints desta página são prefixados com /v1. Exemplo: criar transação em https://app.orbepay.vip/api/v1/transactions.

Autenticação

Use o API Secret (sk_live_…) no cabeçalho:

api-secret: SEU_API_SECRET

Também aceitamos Authorization: Bearer sk_live_….

O secret fica em Integrações → API. Se houver IPs autorizados, o cashout via API só sai desses IPs.

Consultar informações da conta

GET https://app.orbepay.vip/api/v1/account-info

Resposta

{
  "email": "loja@email.com",
  "name": "Loja Exemplo",
  "accountId": "op_000000000003a1b2c3d4",
  "company": "Minha marca",
  "kycStatus": "approved",
  "balance": 1500.5,
  "pendingBalance": 80
}

Consultar transação

GET https://app.orbepay.vip/api/v1/transactions/:id

id pode ser o ID público da cobrança, o external_id ou o ID interno.

{
  "id": "CHGA1B2C3D4",
  "external_id": "pedido-1001",
  "status": "PENDING",
  "amount": 10,
  "payment_method": "PIX",
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "24125439095"
  },
  "pix": { "payload": "00020126..." },
  "pay_link": "https://orbepay.vip/p/CHGA1B2C3D4",
  "hasError": false
}

Criar transação

POST https://app.orbepay.vip/api/v1/transactions

Corpo da requisição

{
  "external_id": "pedido-1001",
  "total_amount": 100.5,
  "payment_method": "PIX",
  "webhook_url": "https://suaapi.com/orbepay",
  "items": [
    {
      "id": "sku-1",
      "title": "Curso digital",
      "price": 100.5,
      "quantity": 1
    }
  ],
  "ip": "187.0.0.1",
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "phone": "11999999999",
    "document": "24125439095"
  },
  "splits": [
    { "recipient_id": "op_000000000004e5f6a7b8", "percentage": 10 },
    { "email": "afiliado@email.com", "percentage": 5 }
  ]
}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`external_id`	string	Não	Seu identificador. Precisa ser único na conta.
`total_amount`	number	Sim	Valor em reais (mínimo R$ 1,00). Alias: `amount`.
`payment_method`	string	Sim	Atualmente `PIX`.
`webhook_url`	string	Não	URL extra para o postback desta cobrança.
`items`	array	Não	Itens da venda (o primeiro vira o nome do produto).
`customer`	object	Sim	Nome, e-mail, telefone e CPF/CNPJ.
`splits`	array	Não	Até 10 contas OrbePay. Soma máxima 80%.

Divisão de pagamento (Splits)

O split reparte o valor pago entre a sua conta e outras contas OrbePay com KYC aprovado. Não há teto de 3 contas: o limite é 10 destinatários por cobrança.

recipient_id — ID da conta (op_… no perfil) ou
email — e-mail da conta OrbePay
percentage — de 0.01 a 80. A soma de todos os splits ≤ 80%

A taxa da plataforma sai da sua parte. No pagamento:

você recebe valor − taxa − splits
cada destinatário recebe o percentual sobre o valor bruto

Cadastre as contas em Financeiro → Contas bancárias → Contas split, ou envie direto no JSON da cobrança.

Resposta

{
  "id": "CHGA1B2C3D4",
  "external_id": "pedido-1001",
  "status": "PENDING",
  "total_value": 100.5,
  "customer": { "email": "joao@email.com", "name": "João Silva" },
  "payment_method": "PIX",
  "pix": { "payload": "00020126...", "qrcode": "https://..." },
  "pay_link": "https://orbepay.vip/p/CHGA1B2C3D4",
  "splits": [
    { "accountId": "op_000000000004e5f6a7b8", "percentage": 10, "amount": 10.05 }
  ],
  "hasError": false
}

Status da transação

PENDING — aguardando pagamento
AUTHORIZED — pago
FAILED — recusado ou expirado
REFUNDED — estornado
CHARGEBACK — chargeback

Webhook de transações

Quando o status muda, a OrbePay envia POST JSON para as URLs cadastradas em Integrações → Webhooks e, se houver, para o webhook_url da cobrança.

{
  "event": "AUTHORIZED",
  "sentAt": "2026-09-02T12:00:00-03:00",
  "transactionId": 123,
  "externalId": "pedido-1001",
  "amount": 100.5,
  "fee": 4.02,
  "net": 86.43,
  "method": "pix",
  "status": "approved"
}

Cabeçalhos: X-OrbePay-Event, X-OrbePay-Token (token do webhook do painel).

Eventos aceitos no cadastro do painel incluem transaction_created, transaction_paid, approved, transfer_completed.

Responda 200 rapidamente. A OrbePay também dispara transaction_paid e approved no pagamento confirmado.

Cashout

POST https://app.orbepay.vip/api/v1/cashout

{
  "external_id": "saque-88",
  "pix_key": "12345678900",
  "pix_type": "CPF",
  "amount": 100.5,
  "webhook_url": "https://suaapi.com/cashout"
}

Parâmetro	Tipo	Descrição
`pix_key`	string	CPF, CNPJ, e-mail, telefone ou chave aleatória
`pix_type`	enum	CPF, CNPJ, EMAIL, PHONE, RANDOM
`amount`	number	Valor em reais. Mínimo R$ 5,00. A taxa de saque é debitada à parte.

Resposta

{
  "id": "42",
  "status": "PENDING",
  "amount": 100.5,
  "pix_key": "12345678900",
  "pix_type": "CPF",
  "created_at": "2026-09-02T12:00:00-03:00"
}

Webhook de cashout

Status possíveis: approved, pending, processing, failed, rejected.

{
  "id": "42",
  "external_id": "saque-88",
  "status": "approved",
  "total_amount": 100.5,
  "pix_key": "12345678900"
}

Erros

Código	Descrição
401	API Secret ausente ou inválida
403	KYC pendente/reprovado, ou IP não autorizado no cashout
400	Dados inválidos (valor, documento, split, etc.)
404	Recurso não encontrado
500	Erro interno

{
  "ok": false,
  "error": "ERROR",
  "message": "Informe o nome do cliente"
}