Webhook - Atualização de Status

Este webhook é enviado sempre que o status de pagamento de uma venda é atualizado.

🔔 Quando é Disparado: Este webhook é enviado quando:
• Um pagamento PIX é confirmado
• Um pagamento é recusado
• Um pagamento é estornado
• Um chargeback é recebido

Estrutura do Payload

Campo	Tipo	Descrição
`event`	string	Tipo do evento (order.created, order.paid, order.processing, order.cancelled, order.chargeback, order.refunded, order.expired)
`title`	string	Título do pedido (ex: "Loja \| Pedido gWswsHZo Paid")
`platform`	string	Plataforma de origem (ex: "AproveiCheckout")
`orderId`	string	Identificador único do pedido
`status`	string	Status do pagamento (ver tabela abaixo)
`statusName`	string	Nome legível do status (ex: "Aprovado")
`paymentMethod`	string	Método de pagamento (ex: "pix")
`createdAt`	datetime	Data de criação do pedido (ISO 8601)
`updatedAt`	datetime	Data da última atualização (ISO 8601)
`approvedDate`	datetime\|null	Data de aprovação do pagamento
`refundedAt`	datetime\|null	Data de estorno/chargeback

Customer (cliente)

Campo	Tipo	Descrição
`customer.name`	string	Nome completo do cliente
`customer.email`	string	E-mail do cliente
`customer.phone`	string	Telefone do cliente
`customer.document`	string	CPF do cliente
`customer.ip`	string	Endereço IP do cliente

Products (produtos)

Array com os produtos da venda

Campo	Tipo	Descrição
`products[x].id`	integer	ID do produto
`products[x].name`	string	Nome do produto
`products[x].quantity`	integer	Quantidade
`products[x].priceInCents`	integer	Preço unitário em centavos
`products[x].priceFinalInCents`	integer	Preço final em centavos (após descontos)
`products[x].image`	string\|null	URL da imagem do produto

Commission (comissão)

Campo	Tipo	Descrição
`commission.totalPriceInCents`	integer	Valor total em centavos
`commission.checkoutFeeInCents`	integer	Taxa do checkout em centavos
`commission.gatewayFeeInCents`	integer	Taxa do gateway em centavos
`commission.userCommissionInCents`	integer	Comissão do usuário em centavos

Address (endereço)

Campo	Tipo	Descrição
`address.street`	string	Logradouro
`address.number`	string	Número
`address.complement`	string\|null	Complemento
`address.neighborhood`	string	Bairro
`address.city`	string	Cidade
`address.state`	string	Estado (UF)
`address.zipcode`	string	CEP
`address.country`	string	País (código ISO)

TrackingParameters (rastreamento)

Campo	Tipo	Descrição
`trackingParameters.src`	string\|null	Origem do tráfego
`trackingParameters.sck`	string\|null	Parâmetro Sck
`trackingParameters.utm_source`	string\|null	UTM Source
`trackingParameters.utm_campaign`	string\|null	UTM Campaign
`trackingParameters.utm_medium`	string\|null	UTM Medium
`trackingParameters.utm_content`	string\|null	UTM Content
`trackingParameters.utm_term`	string\|null	UTM Term

Payments (pagamentos)

Array com os pagamentos realizados

Campo	Tipo	Descrição
`payments[x].payment_method`	string	Método de pagamento
`payments[x].transaction_id_gateway`	string	ID da transação no gateway
`payments[x].amount`	string	Valor pago (formato decimal)
`payments[x].installments`	integer	Número de parcelas
`payments[x].paid_at`	datetime	Data do pagamento (ISO 8601)

Store (loja)

Campo	Tipo	Descrição
`store.id`	integer	ID da loja
`store.name`	string	Nome da loja
`store.slug`	string	Slug da loja

Status de Pagamento

Status	Descrição
`pending`	Pendente - aguardando confirmação
`paid`	Aprovado - pagamento confirmado
`processing`	Processando - pagamento em análise
`cancelled`	Cancelado
`chargeback`	Chargeback recebido
`refunded`	Estornado
`expired`	Expirado

Exemplo de Webhook - Pagamento Aprovado

JSON Payload

{
  "event": "order.paid",
  "title": "Wrath Store | Pedido gWswsHZo Paid",
  "platform": "AproveiCheckout",
  "orderId": "gWswsHZo",
  "status": "paid",
  "statusName": "Aprovado",
  "paymentMethod": "pix",
  "createdAt": "2026-02-20T00:28:39.000000Z",
  "updatedAt": "2026-02-20T00:30:02.000000Z",
  "approvedDate": "2026-02-20T00:30:02.000000Z",
  "refundedAt": null,
  "customer": {
    "name": "João Miguel Costa",
    "email": "joaomiguel.costa@outlook.com",
    "phone": "1522664885",
    "document": "67743776450",
    "ip": "127.0.0.1"
  },
  "products": [
    {
      "id": 25,
      "name": "Cortina Blackout",
      "quantity": 1,
      "priceInCents": 4200,
      "priceFinalInCents": 4200,
      "image": null
    }
  ],
  "commission": {
    "totalPriceInCents": 5100,
    "checkoutFeeInCents": 77,
    "gatewayFeeInCents": 528,
    "userCommissionInCents": 1195
  },
  "address": {
    "street": "Rua Coriolano Durand",
    "number": "34159",
    "complement": null,
    "neighborhood": "Vila Santa Catarina",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "04375050",
    "country": "BR"
  },
  "trackingParameters": {
    "src": null,
    "sck": null,
    "utm_source": null,
    "utm_campaign": null,
    "utm_medium": null,
    "utm_content": null,
    "utm_term": null
  },
  "trackingNumber": null,
  "payments": [
    {
      "payment_method": "pix",
      "transaction_id_gateway": "40694866",
      "amount": "51.00",
      "installments": 1,
      "paid_at": "2026-02-20T00:30:02.000000Z"
    }
  ],
  "store": {
    "id": 4,
    "name": "Wrath Store",
    "slug": "wrath-store"
  }
}

Exemplo de Webhook - Pagamento Estornado

JSON Payload

{
  "event": "order.refunded",
  "title": "Wrath Store | Pedido gWswsHZo Refunded",
  "platform": "AproveiCheckout",
  "orderId": "gWswsHZo",
  "status": "refunded",
  "statusName": "Estornado",
  "paymentMethod": "pix",
  "createdAt": "2026-02-20T00:28:39.000000Z",
  "updatedAt": "2026-02-20T01:15:00.000000Z",
  "approvedDate": "2026-02-20T00:30:02.000000Z",
  "refundedAt": "2026-02-20T01:15:00.000000Z",
  "customer": {
    "name": "João Miguel Costa",
    "email": "joaomiguel.costa@outlook.com",
    "phone": "1522664885",
    "document": "67743776450",
    "ip": "127.0.0.1"
  },
  "products": [
    {
      "id": 25,
      "name": "Cortina Blackout",
      "quantity": 1,
      "priceInCents": 4200,
      "priceFinalInCents": 4200,
      "image": null
    }
  ],
  "commission": {
    "totalPriceInCents": 5100,
    "checkoutFeeInCents": 77,
    "gatewayFeeInCents": 528,
    "userCommissionInCents": 1195
  },
  "address": {
    "street": "Rua Coriolano Durand",
    "number": "34159",
    "complement": null,
    "neighborhood": "Vila Santa Catarina",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "04375050",
    "country": "BR"
  },
  "trackingParameters": {
    "src": null,
    "sck": null,
    "utm_source": null,
    "utm_campaign": null,
    "utm_medium": null,
    "utm_content": null,
    "utm_term": null
  },
  "trackingNumber": null,
  "payments": [
    {
      "payment_method": "pix",
      "transaction_id_gateway": "40694866",
      "amount": "51.00",
      "installments": 1,
      "paid_at": "2026-02-20T00:30:02.000000Z"
    }
  ],
  "store": {
    "id": 4,
    "name": "Wrath Store",
    "slug": "wrath-store"
  }
}

Exemplo de Implementação

PHP

<?php

// Recebe o payload
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

// Log para debug
error_log("Webhook recebido: " . json_encode($data));

// Extrai informações importantes
$orderId = $data['orderId'];
$status = $data['status'];
$totalAmount = $data['commission']['totalPriceInCents'] ?? 0;

// Verifica se já processou este webhook
if (webhookJaProcessado($orderId)) {
    http_response_code(200);
    echo json_encode(['status' => 'already_processed']);
    exit;
}

// Processa baseado no status
switch ($status) {
    case 'paid':
        // Marca pedido como pago
        atualizarPedido($orderId, [
            'status' => 'paid',
            'orderId' => $orderId,
            'paid_at' => $data['approvedDate']
        ]);

        // Envia e-mail de confirmação
        enviarEmailConfirmacao($orderId);

        // Libera produtos digitais
        liberarProdutosDigitais($orderId);
        break;

    case 'refunded':
    case 'chargeback':
        // Marca pedido como estornado
        atualizarPedido($orderId, [
            'status' => 'refunded',
            'refunded_at' => $data['refundedAt']
        ]);

        // Notifica o cliente
        enviarEmailEstorno($orderId);

        // Remove acesso a produtos digitais
        revogarAcessoProdutos($orderId);
        break;

    case 'cancelled':
        // Marca pedido como cancelado
        atualizarPedido($orderId, [
            'status' => 'cancelled'
        ]);
        break;
}

// Marca webhook como processado
marcarWebhookComoProcessado($orderId);

// Retorna sucesso
http_response_code(200);
echo json_encode(['status' => 'success']);

⚠️ Importante: Sempre valide e sanitize os dados recebidos antes de processar. Implemente controles de idempotência para evitar processar o mesmo webhook múltiplas vezes.

💡 Dica: Use o orderId para identificar o pedido no seu sistema. Certifique-se de armazenar o orderId para referência futura e suporte.