Monitor and reconcile

• Customer Hub
• API

For a refresher on what each status means, see How it works → Lifecycle and statuses.

Retrieve the payment link to read its current status. The link's ID goes in the PaymentLinkId header, not the URL:

curl https://api.shift4.com/api/rest/v1/paymentlinks/retrieve \
  -H "AccessToken: YOUR_ACCESS_TOKEN" \
  -H "InterfaceVersion: 1.0" \
  -H "InterfaceName: YourApp" \
  -H "CompanyName: YourCompany" \
  -H "PaymentLinkId: link_8kdskX8DZ8FR6W3acYPXiyAN"

{
  "result": [
    {
      "dateTime": "2026-05-13T09:18:23.283-07:00",
      "paymentLink": {
        "id": "link_8kdskX8DZ8FR6W3acYPXiyAN",
        "status": "active",
        "url": "https://pay.shift4.com/link_8kdskX8DZ8FR6W3acYPXiyAN",
        "lastOpened": "2026-05-13T08:55:12.000Z",
        "restrictions": {
          "payments": {
            "limit": 100,
            "count": 12
          },
          "dates": {
            "expiresAt": "2026-05-27T12:00:00.000Z"
          }
        }
      }
    }
  ]
}

The status field is one of active, scheduled, deactivated, expired, or completed. restrictions.payments.count is the running tally of successful payments, and lastOpened (ISO 8601) is the last time the payment link was visited. Polling works but notifications (below) are preferred for anything real-time.

API reference pointer: Retrieve payment link.

There is no dedicated charges endpoint on a payment link — every payment made through a link produces a Checkout Session, and you can list the sessions filtered by PaymentLinkId:

curl https://api.shift4.com/api/rest/v1/checkoutsessions/list \
  -H "AccessToken: YOUR_ACCESS_TOKEN" \
  -H "InterfaceVersion: 1.0" \
  -H "InterfaceName: YourApp" \
  -H "CompanyName: YourCompany" \
  -H "PaymentLinkId: link_8kdskX8DZ8FR6W3acYPXiyAN"

{
  "hasMore": false,
  "result": [
    {
      "dateTime": "2026-05-13T09:25:11.000Z",
      "paymentLink": {
        "id": "link_8kdskX8DZ8FR6W3acYPXiyAN"
      },
      "checkoutSession": {
        "id": "chse_wMCUGVZgpf45fWHzKbYWMKmZ",
        "staticFields": {
          "Invoice number": "ORD-4421"
        },
        "customFields": [
          {
            "key": "shoe_size",
            "label": "Shoe size",
            "optional": false,
            "value": "10"
          }
        ],
        "lastTransaction": { /* sale response — card brand, last 4, amount, capture status, etc. */ }
      }
    }
  ]
}

Each session's lastTransaction holds the underlying sale response — card brand, last 4, captured amount, and so on — which is what you need for reconciliation.

All filtering and pagination is controlled via headers. The available headers for list endpoints are:

When hasMore: true is returned in the response, pass the last result's id as StartingAfterId on the next request to fetch the next page.

API reference pointer: List checkout sessions.

Notifications are the recommended way to stay in sync with payment link activity — no polling, and you get an event the moment something changes. Configure your notification URL during merchant boarding and Shift4 will POST events to it. Return a 200 to acknowledge receipt.

Two notification streams cover Payment Links:

• paymentlinks-notification — payment-link state changes.
• checkoutsessions-notification — checkout completed.

Event types you'll receive:

Every notification arrives with the same envelope: an event object identifying the type, a dateTime, and the relevant objects at the top level — paymentLink (and, for checkoutsessions-notification, checkoutSession). For example, a checkout_session_completed delivery:

{
  "event": {
    "type": "checkout_session_completed"
  },
  "dateTime": "2026-05-13T09:25:11.000Z",
  "paymentLink": {
    "id": "link_8kdskX8DZ8FR6W3acYPXiyAN"
  },
  "checkoutSession": {
    "id": "chse_wMCUGVZgpf45fWHzKbYWMKmZ",
    "staticFields": {
      "Invoice number": "ORD-4421"
    },
    "customFields": [
      {
        "key": "shoe_size",
        "label": "Shoe size",
        "optional": false,
        "value": "10"
      }
    ],
    "lastTransaction": { /* sale response */ }
  }
}

A payment_link_* event is shaped the same way but with the full paymentLink object (plus customer and metadata) instead of checkoutSession. Use event.type to route to the right handler.

API reference pointers: Payment Links Notification, Checkout Sessions Notification.

A Checkout Session is created each time a customer opens the hosted checkout page from the link. The session carries the staticFields and customFields (with the values the customer entered) from the original payment link, plus a lastTransaction containing the underlying sale response — card brand, last four, captured amount, billing address (if collected), shipping address (if collected), and success/failure status. metadata and vendorReference are not on the session — retrieve the payment link separately if you need them for reconciliation.

curl https://api.shift4.com/api/rest/v1/checkoutsessions/retrieve \
  -H "AccessToken: YOUR_ACCESS_TOKEN" \
  -H "InterfaceVersion: 1.0" \
  -H "InterfaceName: YourApp" \
  -H "CompanyName: YourCompany" \
  -H "CheckoutSessionId: chse_wMCUGVZgpf45fWHzKbYWMKmZ"

The response contains the full set of fields the customer filled in plus lastTransaction — the underlying transaction response. Use it for reconciliation, CRM sync, or fulfilment.

You can get the Checkout Session ID from:

• The checkout_session_id query parameter appended to your Return URL.
• The checkoutSession.id field of a checkout_session_completed notification.
• Listing sessions filtered by PaymentLinkId — see See collected payments.

API reference pointer: Retrieve Checkout Session.