Payment Use Cases
One API. Every business model. From a one-page Shopify clone to a global marketplace with split payouts and in-store terminals — the same endpoints, the same auth, the same response shape.
This guide tours the most common Adyen integration patterns. Each section is self-contained — read the one you need, ignore the rest.
Every pattern below maps to specific endpoints documented in the Build section of this portal. Follow the links inline to jump straight to the reference.
Ecommerce checkout
The 90% case. A shopper lands on a product page, picks a method, pays, you ship.
Hosted checkout — fastest path
createCheckoutSession gives you a hosted, fully PCI-compliant checkout that handles cards, wallets (Apple Pay / Google Pay), and 100+ local methods automatically.
Flow:
- Server →
createCheckoutSessionwithamount,currency,countryCode,reference. - Server → return the session
idto your frontend. - Frontend → load Adyen Web Drop-in, point it at the session.
- Shopper completes payment. Adyen handles 3DS, redirects, retries.
- Webhook → confirms the final state.
Custom checkout — full control
If you need bespoke UI, drop down to getPaymentMethods + createPayment.
| Endpoint | Role |
|---|---|
getPaymentMethods | Returns the methods available for this shopper's country, currency, and amount. |
createPayment | Submits the actual authorisation. |
getPaymentDetails | Finalizes payments that require an extra step (3DS, redirect). |
Pro tip: always call getPaymentMethods dynamically — never hard-code your payment list. Adyen rolls out new methods continuously and dynamic lists adapt to shopper geography automatically.
Subscriptions and recurring billing
Charge a saved card on a schedule — without storing PAN data.
Recurring billing breaks into two patterns:
| Pattern | Description | Example |
|---|---|---|
| CIT (Customer-Initiated) | Shopper is on your site and explicitly approves the charge. | "Upgrade my plan" button. |
| MIT (Merchant-Initiated) | You charge a stored token without the shopper present. | Monthly subscription renewal. |
Pattern
- First payment —
createPaymentwithstorePaymentMethod: trueandshopperReference: "<your-customer-id>". This vaults the payment method. - List tokens —
listStoredPaymentMethodsto retrieve what you've vaulted for a shopper. - Subsequent charges —
createPaymentwith thestoredPaymentMethodId,shopperInteraction: "ContAuth", andrecurringProcessingModelset toSubscriptionorUnscheduledCardOnFile. - Clean up —
deleteStoredPaymentMethodwhen a shopper churns or asks to delete their card.
Adyen automatically participates in network token programs (Visa, Mastercard). When a shopper's physical card expires or is reissued, the stored token continues to work — auth rates stay high without any code changes on your side.
Marketplaces and platforms
One shopper payment, many sellers. Split funds at authorisation time — automatically, by rule, or per transaction.
If you run a marketplace, the rules of the game are:
- The buyer sees one charge.
- The sellers each receive their share.
- You keep the platform commission.
- Adyen handles the funds movement, regulatory routing, and 1099 reporting (where applicable).
Endpoints to know
| Endpoint | What it does |
|---|---|
createSplitConfiguration | Define a named splitting rule (e.g. "platform takes 12%, seller gets remainder"). |
createSplitConfigurationRule | Add granular logic — by payment method, country, or amount band. |
updateSplitLogic | Adjust live rules without a redeploy. |
createPayment | Pass the splits array on the payment itself for per-transaction overrides. |
Onboarding sub-merchants
Marketplaces also need to provision their sellers. The company-level endpoints make that programmatic:
createMerchant— spin up a new merchant under your company.activateMerchant— flip it to live when KYC is complete.createCompanyApiCredential+generateCompanyApiKey— give the seller their own keys.
Pay-by-Link
No frontend needed. Generate a URL, send it via SMS / email / WhatsApp, get paid.
Pay-by-Link is the lowest-effort integration Adyen offers — a single API call returns a hosted, branded payment page.
Example
POST /paymentLinks
{
"amount": { "value": 4999, "currency": "EUR" },
"reference": "INV-2026-0042",
"shopperEmail": "shopper@example.com",
"countryCode": "NL",
"expiresAt": "2026-05-27T18:00:00+02:00"
}Response includes a url — send it, that's it.
Endpoints: createPaymentLink, getPaymentLink, updatePaymentLink.
Where it shines
- Invoice-based businesses — attach a link to the invoice PDF.
- Sales-led ecommerce — send a link after a phone or email negotiation.
- Field services — plumber finishes the job, texts the link, gets paid before leaving.
- Restaurants — open-tab payments via QR code at the table.
In-person and omnichannel
A shopper pays in-store today, online next week, on your mobile app the week after — and you recognize them every time.
Terminal management
Your control plane sits on top of physical card readers:
| Endpoint | Use it for |
|---|---|
listTerminals | See every device tied to your account, with status. |
reassignTerminal | Move a device between stores or merchants without re-provisioning. |
scheduleTerminalActions | Push reboots, app installs, config syncs to a device or fleet. |
updateTerminalSettings | Configure receipts, tipping prompts, currency conversion, screensavers. |
updateTerminalLogo | Brand the device idle screen. |
Unified shopper
The key to omnichannel is the shopper reference — a single ID you pass on every transaction, in-store or online. Adyen ties the records together; you get:
- Cross-channel refunds (return an online order in-store, or vice-versa).
- Cross-channel tokens (charge an in-store card later online).
- A unified shopper profile in the Customer Area.
Donations and round-ups
Cause-driven add-ons at checkout — in a single API pattern.
Adyen's donations product runs on top of any existing payment.
| Endpoint | Use it for |
|---|---|
getDonationCampaigns | List the active charities and round-up campaigns you've configured. |
createDonation | Charge the donation against the original payment's payment method. |
The pattern: complete the main payment, prompt the shopper to round up or add a fixed amount, call createDonation referencing the original pspReference. No second authorisation, no second card form.
Partial payments and gift cards
"I want to pay €60 of this €100 order with a gift card and the rest on Visa."
The Orders API exists exactly for this.
createOrder— open a partial-payment session for the full amount.getPaymentMethodBalance— check what's left on a gift card before applying it.createPaymentreferencing the order — apply each tender (gift card, card, wallet) as a sub-payment.cancelOrder— release any unused funds if the shopper bails.
Endpoints: createOrder, cancelOrder, getPaymentMethodBalance.
Modifications — the after-payment lifecycle
Auth is just the start. Every payment may be:
| Action | Endpoint | When |
|---|---|---|
| Captured | capturePayment | At ship time, after manual review, on delayed billing. |
| Refunded | refundPayment | Customer returns the goods. Captured funds flow back. |
| Reversed | reversePayment | Best-effort cancel-or-refund in one call. Use when you don't know whether capture has run. |
| Cancelled | cancelPayment, cancelAuthorisedPayment | Release a still-authorised reservation. |
| Amount-updated | updatePaymentAmount | Hotel adds room service to an existing auth before capture. |
Choosing the right pattern
| If you are building… | Start with |
|---|---|
| A direct-to-consumer ecommerce store | Hosted checkout (createCheckoutSession) + webhooks |
| A SaaS platform with monthly billing | Vault on first payment, then MIT recurring |
| A marketplace or multi-seller platform | Split configurations + company-level merchant onboarding |
| An invoice or sales-led business | Pay-by-Link |
| A retail or hospitality chain | Terminal endpoints + unified shopper-reference strategy |
| A non-profit or cause-driven brand | Payments + Donations |
| Anything with gift cards or vouchers | Orders API |
Have a use case that doesn't fit any of these? Ask the API Integration Assistant in the bottom-right of this portal — it knows every endpoint and most common patterns.