Skip to main content

Status Updates

Notifications​

When a checkoutNotificationUrl is provided, the system delivers webhook notifications for two events:

Checkout status update — sent when the checkout session status changes:

json
{
  "checkout_id": "MY_CHECKOUT_ID",
  "checkout_reference_id": "MY_CHECKOUT_REFERENCE_ID"
}

Payment created through the checkout — sent when a new payment transaction is initiated within the session:

json
{
  "checkout_id": "MY_CHECKOUT_ID",
  "checkout_reference_id": "MY_CHECKOUT_REFERENCE_ID",
  "reference_id": "MY_REFERENCE_ID",
  "payment_token": "MY_PAYMENT_TOKEN"
}
Validating notifications

All notifications are sent from a fixed set of source IP addresses. Add them to the allowlist of your notification endpoint, and always query the Checkout Status endpoint again after each notification you receive, since the notification is only a trigger and does not carry the final status of the transaction. See Validating Notifications on the Payments page for the source IP list and the full procedure.

Checkout Status​

GET /checkout/`{checkoutId}`/status

Retrieves the current status and details of a checkout session.

Response
{
  "id": "MY_CHECKOUT_ID",
  "url": "MY_CHECKOUT_URL",
  "status": "PROCESSING",
  "created_at": "2026-03-05T12:20:03.185175",
  "expires_at": "2026-03-07T12:20:03.111345",
  "reference_id": "MY_CHECKOUT_REFERENCE_ID",
  "refresh_token": "MY_ACCESS_TOKEN"
}

Checkout Transactions​

GET /checkout/`{checkoutId}`/transactions

Returns all payment transactions initiated within a checkout session.

Response
{
  "transactions": [
    {
      "paymentToken": "MY_PAYMENT_TOKEN",
      "method": "PIX",
      "createdAt": "2026-03-05T15:22:54.695",
      "transactionStatus": "PROCESSING",
      "currency": "BRL",
      "refunded_amount": 0,
      "original_amount": 10,
      "original_asset": "BRL",
      "reference": "MY_REFERENCE_ID",
      "checkout_id": "MY_CHECKOUT_ID",
      "expiration_date": "2026-03-07T15:22:55.000",
      "customer_info": {
        "customer_contact": null,
        "tax_id": "00000000000",
        "tax_id_type": "CPF",
        "payer_tax_id": null,
        "payer_tax_id_type": null,
        "payer_name": null
      }
    }
  ],
  "refresh_token": "MY_ACCESS_TOKEN"
}

Send Checkout Notification​

POST /notifications/checkout/`{id}`/send

Manually triggers the resend of a checkout notification.

Response
{
  "id": 123,
  "created_at": "2026-03-06T11:48:20.455",
  "sent_at": "2026-03-06T11:48:20.455",
  "status": "PENDING",
  "http_status": 0,
  "attempts": 1,
  "refresh_token": "MY_ACCESS_TOKEN"
}