# 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",
  klarna: "adyen",
},
```

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

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

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, 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, Bancontact, Apple Pay and Google Pay through PAYONE follow.

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

## 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](/payments/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()`](/sdks/admin#refund).

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

[Add Apple Pay and Google Pay buttons →](/payments/express)