Skip to main content

​
📱 API de Pagamentos - Documentação

​
Visão Geral

A API de pagamentos do Orbita permite processar pagamentos através de múltiplos métodos: PIX, Boleto e Cartão de Crédito. O sistema suporta diferentes adquirentes e oferece webhooks para notificações de status.

​
🔗 Endpoint Principal

​
POST /pay/payments

Inicializa um novo pagamento. API_KEY gerada dentro da plataforma em https://app-v2.orbitapay.com.br/apps Headers Obrigatórios: 
Content-Type: application/json
Authorization: Bearer {API_KEY}

​
✅ Campos Obrigatórios e Opcionais

​
Obrigatórios

  • paymentMethod - Método de pagamento
  • amount - Valor em centavos (ex: 10000 = R$ 100,00)
  • currency - Moeda (sempre “BRL”)
  • paymentDetails - Dados do pagador
    • firstName - Nome
    • lastName - Sobrenome
    • document - CPF/CNPJ
    • documentType - Tipo do documento
    • email - E-mail
    • phoneNumber - Telefone
    • address - Endereço completo

​
Opcionais

  • shipping.fee - Taxa de envio
  • items - Lista de itens/produtos
  • postbackUrl - URL para receber webhooks
  • splits - Lista de splits para divisão de pagamento
  • UTMSource, UTMMedium, UTMCampaign, UTMTerm, UTMContent - Parâmetros UTM para rastreamento

​
Condicionalmente Obrigatórios

  • installments e creditCard - Obrigatórios quando paymentMethod = "credit_card"

​
🔔 Webhooks

O sistema envia webhooks para postbackUrl quando o status da transação muda. O webhook contém transactionId e o novo status.

​
Status Possíveis

StatusDescrição
initialTransação iniciada
pendingAguardando pagamento
approvedPagamento aprovado
declinedPagamento recusado
refundEstorno processado
chargebackChargeback realizado
expiredPagamento expirado
paidPagamento confirmado
cancelledPagamento cancelado

​
🔄 Fluxo de Pagamento

​
1. Inicialização

  • POST /pay/payments com dados do pagamento
  • Sistema valida dados e cria transação
  • Retorna informações específicas do método escolhido

​
2. Processamento

  • PIX: Gera QR Code e código PIX para pagamento
  • Boleto: Gera código de barras do boleto
  • Cartão: Processa pagamento imediatamente

​
3. Notificação

  • Sistema envia webhook para postbackUrl quando status muda
  • Webhook contém transactionId e novo status

​
⚠️ Códigos de Erro

CódigoDescrição
400Dados inválidos na requisição
401API Key inválida ou ausente
422Erro de validação dos dados
500Erro interno do servidor

​
🔧 Configuração de Webhook

Para receber notificações de mudança de status:
  1. Configure uma URL que aceite POST requests
  2. Inclua postbackUrl na requisição de pagamento
  3. Processe o payload JSON recebido
  4. Retorne status HTTP 200 para confirmar recebimento

​
📝 Observações Importantes

  • Valores: Sempre informar em centavos (ex: R$ 100,00 = 10000)
  • Telefone: Apenas números, sem formatação
  • Documentos: CPF com 11 dígitos, CNPJ com 14 dígitos

​
Autenticação

Todos os tokens de autenticação são gerados na plataforma em https://app-v2.orbitapay.com.br/apps