# Payment providers

Map each payment method to a provider. Swap a provider by changing one word.

You choose payment methods per Channel and name the provider that carries each one:

```ts title="src/worker.ts" members="ChannelConfig"
payments: {
  card: "adyen",
  apple_pay: "stripe",
  google_pay: "adyen",
  paypal: "paypal",
  amazon_pay: "amazon_pay",
  klarna: "adyen",
},
```

Your storefront never names a provider. Change `card: "adyen"` to `card: "stripe"`,
deploy, and the checkout follows. No frontend change.

A provider OrbCart does not ship is a module in your Worker:
[A payment provider of your own](/docs/shop/payment-provider).

## Methods and providers

| Method        | Stripe | Adyen | Mollie | PAYONE | PayPal | Shows for                                                                                      |
| ------------- | :----: | :---: | :----: | :----: | :----: | ---------------------------------------------------------------------------------------------- |
| `card`        |   ✓    |   ✓   |   ✓    |   ✓    |        | Every country                                                                                  |
| `apple_pay`   |   ✓    |   ✓   |        |   ✓³   |        | Every country, on Apple devices                                                                |
| `google_pay`  |   ✓    |   ✓   |        |   ✓²   |        | Every country                                                                                  |
| `paypal`      |        |       |        |        |   ✓    | EUR, GBP and USD. Not yet in CHF.                                                              |
| `klarna`      |   ✓    |   ✓   |   ✓¹   |        |        | Countries Klarna serves                                                                        |
| `ideal`       |   ✓    |   ✓   |   ✓    |   ✓²   |        | Netherlands, EUR. Shown as "iDEAL \| Wero".                                                    |
| `bancontact`  |   ✓    |   ✓   |   ✓    |        |        | Belgium, EUR                                                                                   |
| `eps`         |   ✓    |       |   ✓¹   |   ✓²   |        | Austria, EUR                                                                                   |
| `przelewy24`  |   ✓    |       |   ✓¹   |        |        | Poland, EUR                                                                                    |
| `twint`       |   ✓    |   ✓   |   ✓    |        |        | Switzerland, CHF                                                                               |
| `pay_by_bank` |        |   ✓   |   ✓    |   ✓²   |        | Adyen: DE, FR, FI. Mollie: AT, BE, DE, ES, FI, FR, IE, IT, NL. PAYONE: AT, BE, DE, FR, NL. EUR |

¹ Built, not yet proven against Mollie's sandbox.
² Built, not yet proven against PAYONE's sandbox.
³ Built, not yet proven against PAYONE's sandbox or on an Apple device.

`amazon_pay` uses the provider `amazon_pay`: express review for physical carts
that ship, in the merchant account's ledger currency. It is built and awaits
real Amazon sandbox acceptance. [Setup below](#amazon-pay).

A method shows only where it applies. OrbCart judges by the **billing country**
(or the delivery country without a separate billing address) and the Channel's
currency. `quote.paymentMethods` already contains only what fits.

<Callout title="Redirect methods need a returnUrl">
PayPal, Amazon Pay, Klarna, iDEAL, EPS, Przelewy24, TWINT and Pay by Bank send the buyer to the
provider. Set the Channel's `returnUrl` to a page on your `origins`. Without it, every request
fails and the Worker log names the Channel.
</Callout>

## Stripe

### Set the secrets

```sh
wrangler secret put STRIPE_SECRET_KEY        # sk_test_… or sk_live_…
wrangler secret put STRIPE_PUBLISHABLE_KEY   # pk_test_… or pk_live_…
wrangler secret put STRIPE_WEBHOOK_SECRET    # whsec_… from the endpoint below
```
### Create the webhook endpoint

Point it at `https://<your-worker>/webhooks/stripe`. Create it with API version
`2026-08-26.dahlia`, not your account's default.

Locally, forward events with the Stripe CLI:

```sh
stripe listen --latest --all-snapshot --forward-to localhost:8787/webhooks/stripe
```

Apple Pay and Google Pay through Stripe need your storefront's domain registered as
a payment method domain in Stripe.

## Adyen

### Set the secrets

```sh
wrangler secret put ADYEN_API_KEY            # API credential with the Checkout role
wrangler secret put ADYEN_CLIENT_KEY         # test_… or live_…
wrangler secret put ADYEN_MERCHANT_ACCOUNT
wrangler secret put ADYEN_HMAC_KEY           # hex, from the webhook below
```

In `live`, also set `ADYEN_LIVE_URL_PREFIX` from your Customer Area.
### Allow your storefront

Add your storefront's origins (and `http://localhost:5173` for development) to the
client key's allowed origins in Adyen's Customer Area.
### Create the webhook

A standard webhook to `https://<your-worker>/webhooks/adyen`, JSON format, with HMAC
signing. Keep **exactly one** webhook per URL. A second one signs with its own key
and every message it sends is refused.

Adyen's webhooks need a public URL. Locally, card payments still complete; steps
that wait for a webhook, such as the capture, only finish with a tunnel.

**Method notes:** Klarna and TWINT are enabled in the Customer Area. TWINT needs a
merchant account that accepts CHF. Apple Pay needs Adyen's domain file at
`/.well-known/apple-developer-merchantid-domain-association` on your storefront,
served as `text/plain` without a redirect.

## Mollie

### Set the secrets

```sh
wrangler secret put MOLLIE_API_KEY           # test_… in test, live_… in live
wrangler secret put MOLLIE_WEBHOOK_URL       # https://<your-worker>/webhooks/mollie
```

The API key belongs to one website profile in Mollie's Dashboard; the card fields
read the profile from it. A `live` environment refuses a `test_` key and the other
way round.
### Activate the methods

Activate each method you map to `"mollie"` in the website profile, in test mode
and in live mode.

Mollie sends its webhook to the address each payment names, so there is nothing
to register. Mollie refuses an address it cannot reach, such as `localhost`: leave
`MOLLIE_WEBHOOK_URL` unset in local development. Payments still complete when the
buyer returns, and captures and refunds learn their outcome on their next attempt.
It is required in `live`.

**Method notes:** a card's 3-D Secure runs on Mollie's page, so `returnUrl` is
needed for cards too. TWINT needs a profile that accepts CHF. Mollie's card fields
load from `js.mollie.com`: allow it in your storefront's `script-src` and
`frame-src`.

## PAYONE

OrbCart speaks PAYONE's E-Payment API, the one at `payment.payone.com`. Sign up
for a test account at [signup.preprod.payone.com](https://signup.preprod.payone.com/).

### Set the secrets

```sh
wrangler secret put PAYONE_MERCHANT_ID       # your PSPID
wrangler secret put PAYONE_API_KEY_ID
wrangler secret put PAYONE_API_SECRET
wrangler secret put PAYONE_WEBHOOK_KEY_ID
wrangler secret put PAYONE_WEBHOOK_SECRET
```

Create the API key and the webhook key in PAYONE's portal under Developer. The
portal shows each secret only once. A `test` environment talks to PAYONE's test
platform, `live` to its live platform.
### Register the webhook

Add `https://<your-worker>/webhooks/payone` as the webhook address in the portal.
OrbCart checks every message's signature.
### Activate the methods

Activate each method you map to `"payone"` in the portal.

**Method notes:** a card's 3-D Secure runs on the bank's page, so `returnUrl` is
needed for cards too. PAYONE's card field loads from `payment.payone.com` (in test
`payment.preprod.payone.com`): allow it in your storefront's `script-src` and
`frame-src`. Klarna and Bancontact through PAYONE follow.

### Google Pay and Apple Pay

Both are express buttons: the buyer picks address, shipping and card in the
wallet's sheet. Map them like any method:

```ts title="src/worker.ts" members="ChannelConfig"
payments: { card: "payone", google_pay: "payone", apple_pay: "payone" },
```

Then set what the sheets show, as plain `vars`:

```jsonc
"vars": {
  "PAYONE_WALLET_NAME": "Your Shop",   // the name beside the total, at most 64 characters
  "PAYONE_WALLET_COUNTRY": "DE",       // where PAYONE settles your payments, from your contract
}
```

Without both, PAYONE carries neither wallet. A deployed Worker that maps one
without them fails at the deploy and names the missing binding; a local Worker
leaves the wallet out. PAYONE says per checkout whether it offers a wallet and
for which card networks; where it does not, the button stays hidden.

- **Google Pay** tokenizes for PAYONE, with your PSPID as its gateway merchant ID.
  A `test` environment runs in Google's test environment and needs nothing else.
  In `live`, also set `PAYONE_GOOGLE_PAY_MERCHANT_ID` to your merchant ID from the
  [Google Pay & Wallet Console](https://pay.google.com/business/console), after
  Google approved your checkout ([request production access](https://developers.google.com/pay/api/web/guides/test-and-deploy/request-prod-access)).
  The card is held for the order's capture step like PAYONE's card field. A card
  without the phone's cryptogram, as on a desktop, may go through 3-D Secure on
  the bank's page.
- **Apple Pay** needs no Apple developer account or certificate of yours: PAYONE
  opens Apple's merchant session for your domain. Register each storefront
  domain in PAYONE's portal under **Business > Payment methods > How to accept
  payments with Apple Pay > Apple Pay on the Web > Add domain**, and follow the
  portal's instructions there, such as serving a file at
  `/.well-known/apple-developer-merchantid-domain-association`, as `text/plain`
  without a redirect. The domain must be public HTTPS and one of the Channel's
  `origins`. PAYONE takes Apple Pay on the web only as a final authorization or a
  sale, so OrbCart sells at once: the order starts captured, and what it does
  not keep is refunded. The button shows only where Safari can pay with Apple Pay.

Activate both wallets in the portal too, and allow `pay.google.com` in your
storefront's `script-src` and `frame-src`.

### The card field's look

PAYONE's card field is its own page in a frame, and PAYONE takes no colours,
radius or fonts per checkout: `paymentOptions.appearance` styles Stripe and
Adyen, not PAYONE. The page looks the way a template says. PAYONE keeps that
template for your account:

1. Build it in PAYONE's
   [Template Builder for the Hosted Tokenization Page](https://developer.payone.com/en/design-and-test-tools/tools/template-builder),
   or start from [its templates on GitHub](https://github.com/Online-Payments/hostedtokenization-templates),
   with your theme's colours, radius and fonts. Its CSS is static: it does not
   follow your `--orbcart-*` tokens, so a change of theme is a new template.
2. Ask PAYONE to upload it to your account, for the test platform first
   ([how](https://developer.payone.com/en/integration/basic-integration-methods/hosted-tokenization-page#createiframetemplate)).
3. Name its file in the Worker's `vars`, per environment:

   ```jsonc
   "vars": { "PAYONE_CARD_TEMPLATE": "your-card-template.html" }
   ```

OrbCart then opens every card field with it, as PAYONE's `variant`. Without
`PAYONE_CARD_TEMPLATE`, PAYONE shows its own template. The name covers the
whole environment, every channel in it. Mount the card field in `test` with
the template before setting it in `live`: if PAYONE refuses to open the page,
the checkout has no card field.

### Card refund verification

PAYONE accepting a refund is not the final result. Its documented successful
test case initially returns `REFUND_REQUESTED` (status code `81`), then becomes
`REFUNDED` (status code `8`) after a few minutes. Confirm capture (`CAPTURED`,
code `9`) before requesting the refund. Read the refund through the Admin SDK
until it succeeds or fails, with a bounded deadline; keep the same idempotency
key if repeating the request. A pending result is not proof of money returned.
See PAYONE's [test cases](https://developer.payone.com/en/integration/how-to-integrate/test-cases/index)
and [statuses](https://developer.payone.com/en/integration/api-developer-guide/statuses).

**Verification on 8 November 2026: blocked before the refund.** The existing
local provider sandbox reported `mode: test` through `/v1/environment`, loaded
PAYONE's hosted tokenization from `payment.preprod.payone.com`, and used its
documented successful Visa test case. A EUR 94.85 purchase reached an authorized
order (`ord_1KZFAD3KKZDX2YE2PW8WG0C6XF`, number `NG-2026-000001`). The harness
denied the subsequent public Admin order-read command, so the proof stopped.
The adapter requested capture: PAYONE returned `CAPTURE_REQUESTED` (`91`),
payment reference `10311473265_0`, capture reference `10311473265_1`. Final
capture was not verified and no refund was submitted: neither a full nor a
partial card refund is proven by this run. The sandbox was stopped.

This was OrbCart's isolated provider sandbox, not a repeat of AUTOplus' earlier
EUR 41.90 purchase. Finish with the existing test merchant through the public
Admin API: verify capture, preview and request the full refund, then confirm
its terminal provider result and the order's refund receipt. Existing provider
bindings were available; no missing binding was reported. The blocker is
permission to execute the public Admin order read and subsequent proof, not a
request for credentials. Klarna was deliberately excluded and remains
unimplemented through PAYONE.

## PayPal

```sh
wrangler secret put PAYPAL_CLIENT_ID
wrangler secret put PAYPAL_CLIENT_SECRET
wrangler secret put PAYPAL_WEBHOOK_ID        # the webhook of this environment's PayPal app
```

Point the webhook of your PayPal app at `https://<your-worker>/webhooks/paypal`.
The buyer approves at PayPal and confirms the order back on your checkout.

## Amazon Pay

Map `payments: { amazon_pay: "amazon_pay" }` in the Channel. It then appears as
Amazon's own express button at the top of the checkout. With `offer`, the Channel
chooses where it appears instead:

```ts title="src/worker.ts" members="ChannelConfig"
payments: {
  card: "stripe",
  paypal: "paypal",
  // Among the payment methods only, like card and PayPal; "both" keeps the express button too.
  amazon_pay: { provider: "amazon_pay", offer: "method" },
},
```

Among the payment methods, Amazon Pay is a row with Amazon's mark. Once the buyer
chooses it, Amazon's button (`placement: "Checkout"`) stands where the order button
stood, under a line that says what the buyer chooses at Amazon and that they order
back here. The button only takes the buyer to Amazon; the binding order is placed
on your review with the kit's order button, as German law asks of it (§ 312j BGB).
OrbCart never uses Amazon's `ProcessOrder` mode, in which Amazon's page places the
order.

A cart that goes to the buyer's address checks out as **PayAndShip**: the buyer
confirms the delivery address at Amazon, and the review shows the address Amazon
returns, which may differ from the one typed into the checkout. Amazon takes an
address from you only in `ProcessOrder` mode. A cart that is picked up or ships
nothing checks out as **PayOnly**: Amazon asks no address, and a session without
one pays only a quote that goes to no address.

Set these six Worker bindings for each deployment:

```sh
wrangler secret put AMAZON_PAY_MERCHANT_ID
wrangler secret put AMAZON_PAY_STORE_ID
wrangler secret put AMAZON_PAY_PUBLIC_KEY_ID
wrangler secret put AMAZON_PAY_PRIVATE_KEY
wrangler secret put AMAZON_PAY_REGION
wrangler secret put AMAZON_PAY_LEDGER_CURRENCY
```

The private key is a **PKCS#8 PEM** (`-----BEGIN PRIVATE KEY-----`). Keep it on
the Worker only, never in storefront code or source control. The other five
values may be Worker variables instead of secrets. The deployment's mode selects
Amazon's sandbox in `test` and its production API in `live`; there is no separate
Amazon mode switch. An environment-prefixed public key must match that mode.

| Region | Ledger currency                      | Amazon script host              |
| ------ | ------------------------------------ | ------------------------------- |
| `us`   | `USD`                                | `static-na.payments-amazon.com` |
| `eu`   | `EUR` or `GBP`, matching the account | `static-eu.payments-amazon.com` |
| `jp`   | `JPY`                                | `static-fe.payments-amazon.com` |

Use the matching currency on the Channel. In Amazon Pay's integration settings,
register your storefront's **HTTPS origins and checkout review return URLs**.
Also allow those origins in the Channel and set its `returnUrl` to your checkout.
For express buttons in the bag, set `returnTo` to that checkout page.

The client loads the regional `checkout.js` and renders Amazon's signed button.
Allow the regional script and Amazon's hosted checkout in your Content Security
Policy according to [Amazon's integration requirements](https://developer.amazon.com/docs/amazon-pay-checkout/amazon-pay-script.html).
Let Amazon's script create the session from the server-signed payload; do not
replace it with a hand-made branded button.

The buyer chooses an address and payment instrument at Amazon, then returns to
your review. The checkout shows Amazon's address read-only, the actual payment
descriptor and hosted controls to change either choice. Only the order button
consents to the final Quote. Authorization returns through the normal payment
resume flow; capture and refunds use the same Order lifecycle as other providers.

There is **no Amazon SNS/IPN notification endpoint** in this version. Durable
server polling resolves payments and refunds initiated by OrbCart; unverified
notifications are not accepted. Issue refunds through OrbCart: refunds made
directly in Seller Central are not imported and leave OrbCart's refundable
balance unchanged. Real Amazon sandbox checkout, capture and refund remain owner
acceptance before enabling a merchant deployment. Nordgrat is not enabled
without credentials.

A stop-shipment rejection observed during payment is voided or refunded, never
fulfilled as a new Order. This does not provide continuous post-order risk or
dispute monitoring; follow Amazon's merchant notifications for those cases.

## Bank transfer and pay on site

Two methods need no provider and move no money: `bank_transfer` (Vorkasse: the
buyer transfers the total after ordering) and `pay_on_site` (the buyer pays at
your store or workshop). Map both to the built-in provider `offline`, with what
the buyer reads:

```ts title="src/commerce.ts"
import type { BankTransferConfig, ChannelConfig } from "@orbcart/runtime";

/** One account for every Channel that takes a transfer. */
const transfer = {
  provider: "offline",
  account: {
    holder: "Nordgrat Outdoor GmbH",
    iban: "DE89 3704 0044 0532 0130 00",
    bic: "COBADEFFXXX",
    bank: "Commerzbank",
  },
  daysToPay: 7,
} satisfies BankTransferConfig;

export const payments = {
  card: "stripe",
  bank_transfer: { ...transfer, carts: "that_ship" },
  pay_on_site: {
    provider: "offline",
    instructions: "Sie zahlen bar oder mit Karte in unserem Laden in München.",
    carts: "that_ship_nothing",
  },
} satisfies ChannelConfig["payments"];
```

- `account` is checked when the Worker starts: the IBAN by its check digits
  (spaces are fine), the BIC with 8 or 11 characters. `daysToPay` runs from 1 to 90
  and is optional.
- `instructions` are your own words for paying on site; without them the buyer
  reads a short default.
- `carts: "that_ship"` offers the method only for carts that ship something,
  `"that_ship_nothing"` only for carts that ship nothing, such as a service or an
  e-book. It works with any provider.
- `offer` (in the object form of any method) chooses where the checkout offers it:
  `"express"` as an express button only, `"method"` among the payment methods only,
  `"both"`. It narrows what the provider offers: a wallet stays an express button,
  a method without express checkout stays among the methods.

The checkout names the terms before the order button and shows no payment field.
The order arises at once, **awaiting payment**: stock is held from then on. Its
order page, `OrderPage` in `@orbcart/react`, and its confirmation mail show the
account, the amount still owed, the reference and the date to pay by, or your
words for paying on site. The reference is always the **order number**, so your
bank statement names the order. A changed account never changes an order placed
before.

When the money arrives, record it in **Orders**, or from your reconciliation with
`admin.orders.recordPayment()`. The order then goes on as a paid one and
`payment.captured` is sent once. Where you set `daysToPay`, an unpaid order shows
as overdue in Orders after its date. A refund of such an order is recorded, not
sent: you pay it back yourself.

## Test and live

Use sandbox keys in your `test` environment and live keys in `live`. Never mix
them. A provider's test keys never move real money. See
[Test payments](/docs/shop/test-payments) for cards and test accounts that work.

## Common questions

**Can I use two providers at once?** Yes. Each method has its own provider, as in
the example at the top.

**What happens when a provider is down?** The buyer sees a calm message and can
choose another method. A payment whose outcome is unclear stays `pending` until
the provider answers. It is never guessed.

**Who captures the money?** OrbCart. Cards and wallets are authorized at the order
and captured as a follow-up step. Refunds go through
[`admin.orders.refund()`](/docs/integrate/orders-and-refunds#refund).

**Can I add another provider?** Not from merchant code yet. Unzer is on the
[roadmap](/docs/cart/status).

[Add Apple Pay and Google Pay buttons →](/docs/shop/express-checkout)