Skip to content
Payment Links/
/
API
Last updated

Get started

This quickstart walks through the happy path from both sides of the product: creating a link in the Customer Hub, and creating one programmatically via the API. Pick the scenario that matches how you work.

API quickstart

Create and manage payment links programmatically. You authenticate once, create a link with a minimal payload, share the returned URL with your customer, and confirm payment via the post-payment redirect, a webhook, or the checkout session.

The examples below use curl; adapt the request bodies to your language or HTTP client of choice.

All parameters are passed as HTTP request headers — not in the URL or as query parameters. There are no resource IDs in the URL path and no ?key=value query strings. Every value the API needs — including resource IDs, pagination cursors, and date filters — goes in a named header:

  • Authentication and routing: AccessToken, InterfaceVersion, InterfaceName, CompanyName — required on every request.
  • Resource selection: PaymentLinkId (to target a specific link on retrieve, update, or session list) and CheckoutSessionId (to retrieve a specific session).
  • Pagination and filtering: Limit, StartingAfterId, EndingBeforeId, DatetimeAfter, DatetimeBefore — on list endpoints.

  1. Authenticate. Follow the Quick Start to exchange your Client GUID and Auth Token for an Access Token, then include AccessToken, InterfaceVersion, InterfaceName, and CompanyName headers on every subsequent request.

  2. Create a payment link. POST to /paymentlinks/create with a paymentLink.lineItems array. Each line item wraps a product with a name, a currencyCode (ISO 4217 three-letter code), and an amount object containing total (in major units — 10 = $10.00). For the happy path, a single line item with one product is enough.

    curl -X POST https://api.shift4.com/api/rest/v1/paymentlinks/create \
  -H "AccessToken: YOUR_ACCESS_TOKEN" \
  -H "InterfaceVersion: 1.0" \
  -H "InterfaceName: YourApp" \
  -H "CompanyName: YourCompany" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentLink": {
      "lineItems": [
        {
          "product": {
            "name": "Order #1234",
            "currencyCode": "USD",
            "amount": {
              "total": 10
            }
          }
        }
      ],
      "returnUrl": "https://yourapp.example.com/after-payment"
    }
  }'

  3. Set returnUrl. The URL the customer is redirected to after payment (included in the request above). Shift4 appends status=success and checkout_session_id=<id> as query parameters on redirect. If you don't set returnUrl, the default from your Checkout Settings is used.

  4. Share the returned url. The response wraps a single result object containing paymentLink.id, paymentLink.status (active), and paymentLink.url — the hosted checkout URL on pay.shift4.com. Send url to the customer.

    {
  "result": [
    {
      "dateTime": "2026-05-13T09:18:23.283-07:00",
      "paymentLink": {
        "id": "link_8kdskX8DZ8FR6W3acYPXiyAN",
        "status": "active",
        "url": "https://pay.shift4.com/link_8kdskX8DZ8FR6W3acYPXiyAN",
        "returnUrl": "https://yourapp.example.com/after-payment",
        "lineItems": [
          {
            "product": {
              "name": "Order #1234",
              "currencyCode": "USD",
              "amount": {
                "total": 10
              }
            }
          }
        ]
      }
    }
  ]
}

  5. Confirm the payment. When the customer completes checkout, they're redirected back to your returnUrl with status=success and checkout_session_id=<id> appended. Use the checkout_session_id to read the payment details from /checkoutsessions/retrieve (the session ID goes in the CheckoutSessionId header):

    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 checkout session with customFields (the answers the customer entered), staticFields (the read-only context you set on the link), and lastTransaction — the underlying transaction response.

  6. Listen for webhook events. For a server-side source of truth, configure your notification URL during merchant boarding and Shift4 will POST events to it. Two notifications cover the Payment Links flow:

    • checkoutsessions-notification with event.type = checkout_session_completed — fires when a customer completes checkout via the payment link. Listen for this to confirm payment without polling.
    • paymentlinks-notification with event.type in payment_link_created, payment_link_updated — useful to sync payment-link state.

    Example checkout_session_completed payload:

    {
  "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 */ }
  }
}

    For paymentlinks-notification the body is the payment link object alongside event and dateTime (no checkoutSession). Return a 200 to acknowledge receipt.

If you need…

Next steps

Lifecycle and statuses

Understand the states a payment link moves through.

Link types

Compare fixed-amount and customer-chosen amount links.

Create link

Add expiry dates, address collection, and more configuration options.

Share

Distribute your link and send email notifications to customers.

Customer Hub

Create link