{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["pageIntro","admonition","cards","card"]},"type":"markdown"},"seo":{"title":"API quickstart","description":"Shift4 Payment Platform REST API.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"PageIntro","attributes":{"title":"Get started","active":"api"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This quickstart walks through the happy path from both sides of the product: creating a link in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Customer Hub"]},", and creating one programmatically via the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API"]},". Pick the scenario that matches how you work."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-quickstart","__idx":0},"children":["API quickstart"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The examples below use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["curl"]},"; adapt the request bodies to your language or HTTP client of choice."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["?key=value"]}," query strings. Every value the API needs — including resource IDs, pagination cursors, and date filters — goes in a named header:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication and routing:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AccessToken"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["InterfaceVersion"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["InterfaceName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CompanyName"]}," — required on every request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resource selection:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PaymentLinkId"]}," (to target a specific link on retrieve, update, or session list) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutSessionId"]}," (to retrieve a specific session)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pagination and filtering:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Limit"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["StartingAfterId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EndingBeforeId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DatetimeAfter"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DatetimeBefore"]}," — on list endpoints."]}]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authenticate."]}," Follow the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/quickstart"},"children":["Quick Start"]}," to exchange your Client GUID and Auth Token for an Access Token, then include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AccessToken"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["InterfaceVersion"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["InterfaceName"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CompanyName"]}," headers on every subsequent request."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create a payment link."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/paymentlinks/create"]}," with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentLink.lineItems"]}," array. Each line item wraps a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product"]}," with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},", a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currencyCode"]}," (ISO 4217 three-letter code), and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," object containing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," (in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["major units"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["10"]}," = $10.00). For the happy path, a single line item with one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product"]}," is enough."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.shift4.com/api/rest/v1/paymentlinks/create \\\n  -H \"AccessToken: YOUR_ACCESS_TOKEN\" \\\n  -H \"InterfaceVersion: 1.0\" \\\n  -H \"InterfaceName: YourApp\" \\\n  -H \"CompanyName: YourCompany\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"paymentLink\": {\n      \"lineItems\": [\n        {\n          \"product\": {\n            \"name\": \"Order #1234\",\n            \"currencyCode\": \"USD\",\n            \"amount\": {\n              \"total\": 10\n            }\n          }\n        }\n      ],\n      \"returnUrl\": \"https://yourapp.example.com/after-payment\"\n    }\n  }'\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnUrl"]},"."]}," The URL the customer is redirected to after payment (included in the request above). Shift4 appends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status=success"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout_session_id=<id>"]}," as query parameters on redirect. If you don't set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnUrl"]},", the default from your Checkout Settings is used."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Share the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]},"."]}," The response wraps a single result object containing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentLink.id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentLink.status"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["active"]},"), and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentLink.url"]}," — the hosted checkout URL on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pay.shift4.com"]},". Send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]}," to the customer."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"result\": [\n    {\n      \"dateTime\": \"2026-05-13T09:18:23.283-07:00\",\n      \"paymentLink\": {\n        \"id\": \"link_8kdskX8DZ8FR6W3acYPXiyAN\",\n        \"status\": \"active\",\n        \"url\": \"https://pay.shift4.com/link_8kdskX8DZ8FR6W3acYPXiyAN\",\n        \"returnUrl\": \"https://yourapp.example.com/after-payment\",\n        \"lineItems\": [\n          {\n            \"product\": {\n              \"name\": \"Order #1234\",\n              \"currencyCode\": \"USD\",\n              \"amount\": {\n                \"total\": 10\n              }\n            }\n          }\n        ]\n      }\n    }\n  ]\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Confirm the payment."]}," When the customer completes checkout, they're redirected back to your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnUrl"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status=success"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout_session_id=<id>"]}," appended. Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout_session_id"]}," to read the payment details from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/checkoutsessions/retrieve"]}," (the session ID goes in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutSessionId"]}," header):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl https://api.shift4.com/api/rest/v1/checkoutsessions/retrieve \\\n  -H \"AccessToken: YOUR_ACCESS_TOKEN\" \\\n  -H \"InterfaceVersion: 1.0\" \\\n  -H \"InterfaceName: YourApp\" \\\n  -H \"CompanyName: YourCompany\" \\\n  -H \"CheckoutSessionId: chse_wMCUGVZgpf45fWHzKbYWMKmZ\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response contains the checkout session with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customFields"]}," (the answers the customer entered), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["staticFields"]}," (the read-only context you set on the link), and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastTransaction"]}," — the underlying transaction response."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutsessions-notification"]}]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event.type = checkout_session_completed"]}," — fires when a customer completes checkout via the payment link. Listen for this to confirm payment without polling."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentlinks-notification"]}]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event.type"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_link_created"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_link_updated"]}," — useful to sync payment-link state."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout_session_completed"]}," payload:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event\": {\n    \"type\": \"checkout_session_completed\"\n  },\n  \"dateTime\": \"2026-05-13T09:25:11.000Z\",\n  \"paymentLink\": {\n    \"id\": \"link_8kdskX8DZ8FR6W3acYPXiyAN\"\n  },\n  \"checkoutSession\": {\n    \"id\": \"chse_wMCUGVZgpf45fWHzKbYWMKmZ\",\n    \"staticFields\": {\n      \"Invoice number\": \"ORD-4421\"\n    },\n    \"customFields\": [\n      {\n        \"key\": \"shoe_size\",\n        \"label\": \"Shoe size\",\n        \"optional\": false,\n        \"value\": \"10\"\n      }\n    ],\n    \"lastTransaction\": { /* sale response */ }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentlinks-notification"]}," the body is the payment link object alongside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dateTime"]}," (no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutSession"]},"). Return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," to acknowledge receipt."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["If you need…"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you need custom fields / address collection → ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/payment-links/guides/create-link/api"},"children":["Create link"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you need expiry / max successful payments / scheduling → ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/payment-links/guides/create-link/api"},"children":["Create link"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you need email sending → ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/payment-links/guides/share/api"},"children":["Share"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you need invoice/order reconciliation → ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/payment-links/guides/monitor-and-reconcile/api"},"children":["Monitor and reconcile"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you need full notification event details and payloads → ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/payment-links/guides/monitor-and-reconcile/api#notifications"},"children":["Monitor and reconcile"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":1},"children":["Next steps"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":3,"cardMinWidth":240},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Lifecycle and statuses","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts/payment-links/how-it-works#lifecycle-and-statuses"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Understand the states a payment link moves through."]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Link types","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts/payment-links/how-it-works#link-types"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Compare fixed-amount and customer-chosen amount links."]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Create link","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts/payment-links/guides/create-link/api"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add expiry dates, address collection, and more configuration options."]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Share","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts/payment-links/guides/share/api"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Distribute your link and send email notifications to customers."]}]}]}]},"headings":[{"value":"API quickstart","id":"api-quickstart","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Get started","description":"Create a payment link, share it, and confirm a payment — the happy path for the API.","navigation":{"nextButton":{"label":"Create link","link":"/guides/core-concepts/payment-links/guides/create-link/api"}},"seo":{"title":"API quickstart"}},"lastModified":"2026-07-15T15:46:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/core-concepts/payment-links/get-started/api","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}