Accept Pix payments/
Accept Pix payments/
Track payment status

Track payment status

DocsLimited

Last updated: Sept 11th, 9:34am

After creating the order, you can track the payment status in two ways:

  1. Use webhooks
  2. Optional: Poll for updates

Use webhooks

To track the payment status using webhooks, follow these steps:

  1. Subscribe to webhook events in your PayPal developer dashboard or via the Webhooks API. For example:
    • CHECKOUT.ORDER.APPROVED – Order approval after buyer completes PIX QR code scan or copy-paste action
    • CHECKOUT.ORDER.COMPLETED – Successful order completion after the buyer completes payment through QR code or copy-and-paste code
    • CHECKOUT.PAYMENT-APPROVAL.REVERSED – Failed order processing (for example, cancelled payment, expired QR code)
  2. Define a webhook handler in your server-side application to:
    1. Listen for incoming webhook events.
    2. Confirm receipt of the event to PayPal.
    3. Verify the source of the event notification.
    4. Complete further actions based on event data.

The following example shows a webhook payload for a completed Pix payment:

    1{
    2  "id": "WH-2B342482FC0449155-12X09416XP387753C",
    3  "event_version": "1.0",
    4  "zts": 1481046241,
    5  "create_time": "2022-04-08T10:37:05Z",
    6  "resource_type": "capture",
    7  "resource_version": "2.0",
    8  "event_type": "PAYMENT.CAPTURE.COMPLETED",
    9  "summary": "Payment completed for USD 1.00 USD",
    10  "resource": {
    11    "amount": {
    12      "value": "1.00",
    13      "currency_code": "USD"
    14    },
    15    "create_time": "2022-04-08T10:37:05Z",
    16    "update_time": "2022-04-08T10:37:05Z",
    17    "final_capture": true,
    18    "seller_receivable_breakdown": {
    19      "paypal_fee": {
    20        "value": "0.20",
    21        "currency_code": "USD"
    22      },
    23      "gross_amount": {
    24        "value": "1.00",
    25        "currency_code": "USD"
    26      },
    27      "net_amount": {
    28        "value": "0.80",
    29        "currency_code": "USD"
    30      }
    31    },
    32    "links": [
    33      {
    34        "method": "GET",
    35        "rel": "self",
    36        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/8SS60826HT082593F"
    37      },
    38      {
    39        "method": "POST",
    40        "rel": "refund",
    41        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/8SS60826HT082593F/refund"
    42      },
    43      {
    44        "method": "GET",
    45        "rel": "up",
    46        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5KP92830L1747245S"
    47      }
    48    ],
    49    "id": "8SS60826HT082593F",
    50    "status": "COMPLETED"
    51  },
    52  "links": [
    53    {
    54      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-2B342482FC0449155-12X09416XP387753C",
    55      "rel": "self",
    56      "method": "GET"
    57    },
    58    {
    59      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-2B342482FC0449155-12X09416XP387753C/resend",
    60      "rel": "resend",
    61      "method": "POST"
    62    }
    63  ]
    64}

    Extract the order ID from the "rel": "up" link in the webhook payload’s resource.links array to correlate the capture to your original order.

    Poll for updates

    To check the status of a Pix order, you can poll the Orders API:

    1. Use a valid access token and send a GET request to /v2/checkout/orders/{id}, replacing {id} with the order ID from your Create order response.
    2. Review the response to determine the current order status and act as needed.
    Parameter name Description
    id Unique order ID.
    status Current status of the order. For Pix payments, COMPLETED means the payment capture is successful.
    purchase_units List of purchase units for the order, including amount and currency.
    payer Information about the buyer, including name and payer ID.

    For the comprehensive list of response parameters, see Show order details.

    ReferencePayPal.comPrivacyCookiesSupportLegalContact

    If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more