Skip to main content
POST
/
pay
/
webhook

🔔 Estrutura do Webhook

O sistema envia webhooks para a postbackUrl configurada na requisição de pagamento sempre que o status da transação muda.

Payload do Webhook

transactionId
string
required
ID único da transação
status
string
required
Novo status da transação
customer
object
Dados do cliente
customer.email
string
E-mail do cliente
customer.name
string
Nome completo do cliente
customer.document
string
CPF/CNPJ do cliente
customer.phone
string
Telefone do cliente
amount
number
Valor da transação em centavos
currency
string
Moeda da transação (sempre “BRL”)
paymentMethod
string
Método de pagamento utilizado
utm
object
Dados de rastreamento UTM
utm.source
string
UTM Source
utm.medium
string
UTM Medium
utm.campaign
string
UTM Campaign
utm.term
string
UTM Term
utm.content
string
UTM Content

Exemplo de Payload

{
  "transactionId": "14d486a6-7c9d-4e75-919c-b0a2d1bf49ae",
  "status": "approved",
  "customer": {
    "email": "[email protected]",
    "name": "João Silva",
    "document": "12345678901",
    "phone": "11999999999"
  },
  "amount": 10000,
  "currency": "BRL",
  "paymentMethod": "credit_card",
  "utm": {
    "source": "google",
    "medium": "cpc",
    "campaign": "summer_sale",
    "term": "pagamentos",
    "content": "ad_variant_1"
  }
}

📊 Status Possíveis

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

🔧 Configuração

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

Exemplo de Endpoint de Webhook

// Exemplo em Node.js/Express
app.post('/webhook', (req, res) => {
  const { 
    transactionId, 
    status, 
    customer, 
    amount, 
    currency, 
    paymentMethod,
    utm 
  } = req.body;
  
  // Processar a mudança de status
  console.log(`Transação ${transactionId} mudou para status: ${status}`);
  console.log(`Cliente: ${customer?.name} (${customer?.email})`);
  console.log(`Valor: R$ ${(amount / 100).toFixed(2)}`);
  console.log(`Método: ${paymentMethod}`);
  
  // Atualizar status no banco de dados
  // Enviar notificação ao usuário
  // Processar dados UTM para analytics
  // etc.
  
  // Sempre retornar 200 para confirmar recebimento
  res.status(200).json({ received: true });
});

⚠️ Importante

  • O webhook será enviado sempre que o status da transação mudar
  • Você deve retornar HTTP 200 para confirmar o recebimento
  • Em caso de falha (timeout ou erro), o sistema pode tentar reenviar o webhook
  • Recomenda-se implementar idempotência no processamento dos webhooks

Authorizations

Authorization
string
header
required

API_KEY gerada dentro da plataforma em https://app-v2.orbitapay.com.br/apps

Body

application/json

Dados do webhook

transactionId
string<uuid>
required

ID único da transação

status
enum<string>
required

Status da transação

Available options:
initial,
pending,
approved,
declined,
refund,
chargeback,
expired,
paid,
cancelled
customer
object
amount
number<decimal>

Valor da transação em centavos

currency
enum<string>
default:BRL

Moeda da transação

Available options:
BRL
paymentMethod
string

Método de pagamento utilizado

utm
object

Response

200

Webhook recebido com sucesso