Skip to main content
WEBHOOK
/
pay
/
webhook
{
  "transactionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "initial",
  "customer": {
    "email": "jsmith@example.com",
    "name": "<string>",
    "document": "<string>",
    "phone": "<string>"
  },
  "amount": 123,
  "currency": "BRL",
  "paymentMethod": "<string>",
  "utm": {
    "source": "<string>",
    "medium": "<string>",
    "campaign": "<string>",
    "term": "<string>",
    "content": "<string>"
  }
}

​
🔔 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": "joao@email.com",
    "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