Únicopag - Webhook de Pagamentos | Gateway

Documentação oficial da Webhook - Integre pagamentos em sua aplicação

Visão Geral

Os webhooks pagamentos da Únicopag permitem realizar integrações de forma simples e segura.

📋 Campos Importantes

hash: Identificador único da transação

payment_status: Status atual do pagamento

amount_total: Valor total da transação

customer: Dados completos do cliente

pix: Dados específicos do PIX (QR Code, etc.)

products: Lista de produtos da transação

🔔 Como Funciona

• O webhook é enviado via POST para a URL configurada
• Enviado sempre que o status da transação muda
• Sua aplicação deve responder com status HTTP 200
• Caso não responda, tentaremos reenviar até 5 vezes

⚠️ Configuração

Para receber webhooks, configure o campo postback_url ao criar um pagamento. A URL deve ser HTTPS e estar acessível publicamente.

Status de Pagamento

Lista completa dos possíveis status que uma transação pode assumir

Cada transação possui um status que indica seu estado atual no processo de pagamento.

paid

Pagamento aprovado e processado

processing

Transação sendo processada

pending

Aguardando confirmação

antifraud

Em análise antifraude (Possível apenas para Cartão)

med_received

Documentos recebidos (Possível apenas para Pix)

med_analysis

Em análise manual (Possível apenas para Pix)

refused

Pagamento recusado

failed

Falha no processamento

med_reproved

Reprovado na análise (Possível apenas para Pix)

cancelled

Transação cancelada

refunded

Pagamento estornado

chargeback

Contestação confirmada (Possível apenas para Cartão)

pre_chargeback

Pré-contestação (Possível apenas para Cartão)

💡 Dica

Use o endpoint GET /public/v1/transactions/:hash para consultar o status atual de uma transação específica. O status é retornado no campo status da resposta.

Webhook de Transação

Exemplo de payload enviado pelo webhook quando uma transação muda de status

Quando uma transação muda de status, o Únicopag envia automaticamente um webhook para a URL configurada no campo postback_url com os dados atualizados da transação.

Exemplo de Payload do Webhook

{
  "event": "transaction.created", // or transaction.updated
  "id": "example123",
  "hash": "example123",
  "payment_method": "pix",
  "payment_status": "waiting_payment",
  "installments": 1,
  "amount": 500,
  "amount_discount": 0,
  "amount_shipping": 0,
  "amount_interest": 0,
  "amount_total": 500,
  "customer": {
    "hash": "customerhash123",
    "name": "Fulano da Silva",
    "email": "email@example.com",
    "document": "00000000000",
    "document_type": "cpf",
    "phone_coutry_code": "55",
    "phone_number": "0000000000",
    "country": "br",
    "zip_code": "00000000",
    "street_name": "Rua Exemplo",
    "number": "123",
    "complement": null,
    "neighborhood": "Bairro Exemplo",
    "city": "Cidade Exemplo",
    "state": "SP",
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_term": null,
    "utm_content": null,
    "created_at": "2025-06-05T00:00:00.000000Z",
    "updated_at": "2025-06-09T00:00:00.000000Z",
    "antifraud_validated": 0,
    "last_ip": null
  },
  "pix": {
    "pix_url": null,
    "pix_qr_code": "00020126...<código fictício>...6304XXXX",
    "pix_base64": null
  },
  "billet": null,
  "src": "origem",
  "utm_source": "campanha",
  "utm_campaign": "teste",
  "utm_content": "conteudo",
  "utm_term": "termo",
  "utm_medium": "meio",
  "postback_url": "https://example.com/webhook",
  "paid_at": null,
  "created_at": "2025-06-09 00:00:00",
  "updated_at": "2025-06-10 00:00:00",
  "products": [
    {
      "hash": "producthash123",
      "custom_options": null,
      "price": 500,
      "quantity": 1,
      "operation_type": 1,
      "created_at": "2025-06-09T00:00:00.000000Z",
      "updated_at": "2025-06-09T00:00:00.000000Z",
      "title": "Produto Exemplo"
    }
  ],
  "gateway": {
    "hash": "gatewayhash123",
    "identifier": "GatewayExemplo"
  },
  "link_checkout": null,
  "tracking_code": null,
  "coupon": []
}