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](/guides/quickstart) 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.

```bash
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.

```json
{
  "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):

```bash
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:

```json
{
  "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…**

- If you need custom fields / address collection → [Create link](/guides/core-concepts/payment-links/guides/create-link/api)
- If you need expiry / max successful payments / scheduling → [Create link](/guides/core-concepts/payment-links/guides/create-link/api)
- If you need email sending → [Share](/guides/core-concepts/payment-links/guides/share/api)
- If you need invoice/order reconciliation → [Monitor and reconcile](/guides/core-concepts/payment-links/guides/monitor-and-reconcile/api)
- If you need full notification event details and payloads → [Monitor and reconcile](/guides/core-concepts/payment-links/guides/monitor-and-reconcile/api#notifications)


## 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.