> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment gateways

> Connect Stripe, PayPal, PayPal Friends & Family, Cash App, and crypto.

All gateways are configured from **Settings → Payment gateways** (`/settings/payments/gateways`).
The page has four tabs: **Card**, **Crypto**, **Aggregators**, **Manual**. Connect any combination —
buyers see only what's enabled.

This page walks you through the **setup specifics** for each provider, including the parts that
trip people up. For a high-level overview of how payments flow, see
[How payments work](/merchants/payments/overview).

## Stripe

Cards and wallets (Apple Pay, Google Pay) through Stripe.

### What you'll need

A Stripe account with **API access** — you can sign up at [stripe.com](https://stripe.com) if
you don't have one yet. You'll need to copy two keys from your Stripe dashboard:

* **Publishable Key** — starts with `pk_live_` (or `pk_test_` for testing).
* **Secret Key** — starts with `sk_live_` (or `sk_test_`).

Both are in the Stripe Dashboard at **Developers → API keys**.

### Connecting

1. Open **Settings → Payment gateways → Card** and click **Connect** on Stripe.
2. Paste the **Publishable Key** and **Secret Key** into the dialog.
3. Click **Connect**.

Shoppex validates the keys, then automatically:

* Creates a webhook endpoint on your Stripe account (events: `payment_intent.succeeded`,
  `.payment_failed`, `.canceled`, `charge.refunded`, and the three `charge.dispute.*` events).
* Registers your shop subdomain (`yourshop.shoppex.io`), the shared `checkout.shoppex.io` and
  `embed.shoppex.io` hosts, and any verified custom domain you've connected, for Apple Pay.

### Common pitfalls

* **"Stripe API key must allow Shoppex to create webhook endpoints."** Your secret key is a
  Restricted Key without the Webhook scope. Either generate a normal Secret Key, or grant the
  Restricted Key the `Webhook Endpoints: Write` permission.
* **Apple Pay error during connect.** If Stripe rejects the Apple Pay domain registration for
  your `{shop}.shoppex.io`, the whole Connect fails. Wait a few minutes and retry — Stripe's
  domain registration is sometimes flaky.
* **Test keys vs. live keys.** Shoppex accepts both. Test keys (`sk_test_`) will only see test
  cards at checkout — useful for sandbox runs, but no real money moves. Switch to `sk_live_`
  for production.
* **Disconnect doesn't reconcile pending payments.** If you disconnect Stripe while
  PaymentIntents are still in flight, those payments won't be tracked by Shoppex after the
  disconnect — they continue on Stripe's side. Wait for pending invoices to finalize before
  you disconnect.
* **Stripe-side key revocation.** If Stripe revokes the API key (e.g. account suspended),
  subsequent checkout attempts will fail. Check the **Stripe Dashboard** if Stripe-paid
  orders stop succeeding.

## PayPal (SDK)

The standard PayPal integration. Recommended over Friends & Family unless you have a specific
reason to avoid it.

### What you'll need

A **PayPal Business account** plus REST API credentials. To get those:

1. Go to [developer.paypal.com](https://developer.paypal.com) and log in with your PayPal
   Business account.
2. Open **Apps & Credentials → Live**.
3. Either create a new app or open an existing one. Copy the **Client ID** and **Secret**.

### Connecting

1. Open **Settings → Payment gateways → Card** → **Connect** on PayPal.
2. Paste the **Client ID** and **Client Secret** into the form.
3. Click **Connect**. Shoppex validates the credentials against PayPal's API.

### Register webhooks in PayPal (required)

Unlike Stripe, Shoppex does **not** auto-register PayPal webhooks. You have to add them yourself
in the PayPal Developer Dashboard so that Shoppex receives payment events:

1. In **Apps & Credentials**, click into your app → **Webhooks** → **Add Webhook**.
2. Webhook URL for normal payments: `https://api.shoppex.io/v1/paypal/webhook`
3. Webhook URL for subscriptions: `https://api.shoppex.io/v1/paypal/webhook/subscriptions`

Subscribe to these events:

**For payments**

* `CHECKOUT.ORDER.APPROVED`, `CHECKOUT.ORDER.COMPLETED`
* `PAYMENT.AUTHORIZATION.CREATED`, `PAYMENT.AUTHORIZATION.VOIDED`
* `PAYMENT.CAPTURE.COMPLETED`, `PAYMENT.CAPTURE.DENIED`, `PAYMENT.CAPTURE.PENDING`
* `PAYMENT.CAPTURE.REFUNDED`, `PAYMENT.CAPTURE.REVERSED`
* `CUSTOMER.DISPUTE.CREATED`, `CUSTOMER.DISPUTE.UPDATED`, `CUSTOMER.DISPUTE.RESOLVED`

**For subscriptions** (only if you sell subscription products)

* `BILLING.SUBSCRIPTION.ACTIVATED`, `BILLING.SUBSCRIPTION.CANCELLED`
* `BILLING.SUBSCRIPTION.PAYMENT.FAILED`
* `PAYMENT.SALE.COMPLETED`, `PAYMENT.SALE.REFUNDED`, `PAYMENT.SALE.REVERSED`

Save. Webhook deliveries start flowing immediately.

### Common pitfalls

* **"Invalid PayPal API credentials."** You're using Sandbox credentials, not Live. Sandbox
  apps and Live apps have separate Client IDs and Secrets in the PayPal Developer Console.
* **Orders stuck in pending.** Almost always missing or misconfigured webhooks. Re-check the
  webhook URL and the subscribed events.
* **Currency mismatch.** PayPal requires the buyer's currency to match a currency your PayPal
  account supports. Most accounts handle USD/EUR/GBP fine; less common currencies may bounce.

## PayPal Friends & Family

Lower-friction PayPal that bypasses transaction fees, at the cost of buyer-side protection
(F\&F transactions are not eligible for PayPal Buyer Protection or chargebacks). Setup is
IPN-based, not API-based.

### What you'll need

* A **PayPal Business** account (Personal works too, with the IPN feature enabled).
* Your PayPal account email.

### Connecting

1. Open **Settings → Payment gateways → Manual** → **Connect** on PayPal F\&F.
2. Enter the **PayPal email** where buyers will send Friends & Family payments.
3. Click **Connect PayPal F\&F**.

Shoppex shows you the IPN URL to use: `https://paypal-ff.myshoppex.io`. This URL is the same
for all Shoppex shops — incoming IPNs are matched to your shop by the **invoice ID** in the
buyer's payment note. Copy it.

### Configure IPN in PayPal

Without IPN, F\&F orders sit in pending forever and need manual verification. To wire it up:

1. Log into PayPal (the Business account, not the Developer Console).
2. **Account Settings → Website Payments → Instant Payment Notifications**.
3. Click **Update**, then **Choose IPN Settings**.
4. Paste `https://paypal-ff.myshoppex.io` as the IPN URL.
5. Turn on **Receive IPN messages**.
6. Save.

PayPal starts forwarding F\&F payments to Shoppex. Shoppex matches each IPN to a pending invoice
by the **invoice ID in the buyer's payment note**.

### Buyer flow

When a buyer pays via F\&F, the Shoppex checkout shows them:

* Your PayPal email address (where to send the money).
* The exact amount.
* A note string (`SX-{invoice-id}`) they need to include in the PayPal note field.

The buyer pays out-of-band on PayPal. PayPal sends the IPN to Shoppex. Shoppex matches by the
note and marks the order paid.

### Common pitfalls

* **Buyer forgot to include the note.** Without the note, Shoppex can't match the IPN to an
  invoice. The order stays pending until you manually verify it from the order page (or the
  buyer disputes / requests a refund through PayPal directly).
* **F\&F doesn't work for cross-border.** PayPal restricts F\&F to domestic transactions in many
  countries. If your buyer is in a different region than your PayPal account, the F\&F option
  might be greyed out for them on PayPal's side.
* **No buyer protection means no chargebacks** — but also means *you* have no recourse if the
  buyer's PayPal account gets compromised or reverses the transfer manually. F\&F should be
  treated as cash-equivalent.

## Cash App

US-only. The flow is **email-forwarding-based**: Cash App doesn't have a public API for
merchants, so Shoppex reads Cash App's receipt emails to confirm payments.

### What you'll need

* An active **Cash App** account with a `$cashtag`.
* A **Gmail address** you control and can set up forwarding from.

### Connecting

1. Open **Settings → Payment gateways → Manual** → **Connect** on Cash App.
2. Enter your **`$cashtag`** (must start with `$`, e.g. `$yourbrand`).
3. Enter the **Gmail address** that receives Cash App receipt emails.
4. Click through to step 2 of the wizard.

Shoppex shows you a **forwarding email address** — something like
`{shop-id}-cashapp@inbound.shoppex.io`. Copy it.

### Set up Gmail forwarding

Cash App setup has **two phases**:

1. **Gmail forwarding confirmation** — Google sends one email to Shoppex to prove the
   forwarding address is reachable.
2. **Receipt pipeline test** — a real Cash App payment receipt must reach Shoppex before the
   gateway shows as verified.

In the Cash App wizard:

1. Open Gmail → **Settings → Forwarding and POP/IMAP** → **Add a forwarding address**.
2. Paste the Shoppex forwarding address from step 2 of the wizard.
3. Gmail sends a confirmation email to Shoppex. Go back to the wizard, click
   **Check Verification Status**, and open the **Google Confirmation Link** if one is shown.
4. Approve forwarding in Gmail.
5. Create a **filter** with criteria `from:cash@square.com OR from:cash@cash.app` and forward
   matching mail to the same Shoppex address.
6. Send yourself a **small test payment** through your shop. Once Shoppex receives the receipt
   email, the wizard shows a green check and the gateway badge clears.

Until step 6 completes, the gateway card may show **Receipt test pending** even after the Gmail
confirmation email arrives. That is expected.

### Buyer flow

At checkout, the buyer sees your `$cashtag` and a unique note code (`SX-{invoice-id}`). They:

1. Open Cash App, send the amount to your `$cashtag`, include the note.
2. Click **I've sent the payment** on the Shoppex checkout (manual confirmation step).

Cash App emails you the receipt. Gmail forwards it to Shoppex. Shoppex matches the email to
the pending invoice and marks it paid.

### Common pitfalls

* **USD only.** Cash App rejects non-USD shops. If your shop's primary currency isn't USD,
  Cash App won't appear in the gateway list.
* **Connect before enable.** You must connect Cash App with your cashtag and Gmail address
  before the checkout toggle can be turned on. Receipt verification is separate and proves the
  forwarding pipeline works.
* **Gmail filter must catch every receipt format.** Cash App occasionally varies their email
  template. If a payment doesn't auto-confirm, check Gmail for the receipt and forward it
  manually as a test.

## Crypto: Aggregators

For multi-coin coverage without managing addresses per chain.

### Cryptomus

API-key-based. Get a key from your [Cryptomus dashboard](https://cryptomus.com) under
**Settings → Payments → API**. You'll also need your **Merchant ID** from the same page.

In Shoppex: **Settings → Payment gateways → Aggregators → Cryptomus → Connect**. Paste both,
save. Cryptomus handles which coins are visible at checkout based on your Cryptomus settings.

### Oxapay

API-key-based, simpler than Cryptomus. Get a Merchant API key from
[Oxapay](https://oxapay.com) → **Merchant API**.

In Shoppex: **Settings → Payment gateways → Aggregators → Oxapay → Connect**. Paste the key.
Oxapay's currently supported coins and networks are fetched live whenever a buyer opens
checkout — whatever you've enabled in your Oxapay dashboard shows up.

## Crypto: Shoppex Wallet

For accepting Bitcoin and Litecoin directly into a wallet only you control — no intermediary.

The **Shoppex Wallet** is a native, **self-custodial** wallet for **BTC** and **LTC**. Buyers pay
straight into a wallet that belongs to you; the keys and recovery phrase are generated on your
device and Shoppex never holds the funds. You create it from the onboarding wizard in **Settings →
Payments → Shoppex Wallet** — there are no per-coin addresses to paste.

See the full guide: [Shoppex Wallet](/merchants/payments/crypto-wallet).

### Pitfalls

* **Self-custody means full responsibility.** If you lose both your wallet password and your
  12-word recovery phrase, Shoppex has no way to recover the funds.
* **No automatic refunds.** Since Shoppex doesn't custody the wallet, crypto refunds are manual —
  you send the funds back yourself from the Wallet area, then mark the order refunded in Shoppex.
  See [Refunds](/merchants/payments/refunds#crypto-refund-amounts).

For multi-coin coverage beyond BTC/LTC, connect a provider (Cryptomus / Oxapay) instead — see
[Crypto: Aggregators](#crypto-aggregators) above.

<Card title="Next: Payouts" href="/merchants/payments/payouts">
  When the money lands for each gateway, and how to reconcile.
</Card>