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

This page walks you through the setup steps for each provider, including the parts that most often cause problems. For a high-level overview of how payments flow, see [Checkout](/payments/checkout).

## Stripe

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

### What you will need

A Stripe account with **API access** is required. If you do not have one, sign up at [stripe.com](https://stripe.com). You will 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 have 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 sometimes fails temporarily.
* **Test keys vs. live keys.** Shoppex accepts both. Test keys (`sk_test_`) only accept test cards at checkout. Use them for sandbox runs, since no real money moves. Switch to `sk_live_` for production.
* **Disconnecting does not check pending payments against Stripe.** If you disconnect Stripe while PaymentIntents are still in flight, Shoppex stops tracking those payments after the disconnect, though they continue on Stripe's side. Wait for pending invoices to finish before you disconnect.
* **Stripe-side key revocation.** If Stripe revokes the API key, for example because the account is suspended, checkouts after that fail. If Stripe-paid orders stop succeeding, check the **Stripe Dashboard**.

## PayPal (SDK)

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

### What you will 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 must 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 are 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, and GBP without issue. Less common currencies can bounce.

## PayPal Friends & Family

A simpler PayPal route that avoids 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 will 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 set 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 through 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 cannot match the IPN to an invoice. The order stays pending until you manually verify it from the order page, or the buyer disputes or requests a refund through PayPal directly.
* **F\&F does not work for cross-border payments.** 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 can appear greyed out for them on PayPal's side.
* **No buyer protection means no chargebacks.** It also means you have no recourse if the buyer's PayPal account is compromised, or if the buyer reverses the transfer manually. Treat F\&F as cash-equivalent.

## Cash App

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

### What you will 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 `$`, for example `$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 and click **Check Verification Status**. If the wizard shows a **Google Confirmation Link**, open it.
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 can 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`, and 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 is not USD, Cash App does not 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 its email template. If a payment does not 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 will 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 have enabled in your Oxapay dashboard shows up.

## Crypto: Shoppex Wallet

For accepting Bitcoin and Litecoin directly into a wallet only you control, with 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](/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.** Because Shoppex does not 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](/payments/refunds#crypto-refund-amounts).

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

## Payouts

Because Shoppex does not custody funds, payouts happen on each gateway's own schedule, not Shoppex's schedule. There is no shared Shoppex balance to withdraw from.

### Per-gateway timing

* **Stripe** — Funds settle to the bank account on your connected Stripe profile on Stripe's rolling payout schedule (set in your Stripe dashboard). New accounts typically start on a delayed schedule and graduate to faster cycles as volume builds. That is Stripe's policy, not Shoppex's.
* **PayPal (SDK)** — Funds land in your PayPal Business balance right after capture. Withdraw from PayPal as you normally do.
* **PayPal Friends & Family** — Funds arrive in your PayPal personal balance as F\&F transfers, per PayPal's own timing.
* **Cryptomus / Oxapay** — Funds accumulate in your provider balance. Withdraw from those providers' dashboards to your wallets or to fiat (where supported).
* **Direct crypto (BTC / LTC / ETH / Lightning)** — Funds arrive at your wallet on-chain once the required confirmations clear, with no intermediary holding them.

### Matching orders to gateway statements

Shoppex tracks every order in your dashboard regardless of which gateway processed it. The **Orders** page lists each order's gateway, amount, and final status. Match those against your gateway statements to check that everything lines up.

### Holds and reserves

Holds, rolling reserves, and reverse-flow refunds are gateway-specific and live in each provider's own dashboard, not in Shoppex. If Stripe puts your account on a reserve, you see it in the Stripe dashboard, and your Shoppex orders continue normally. Stripe controls when the funds disburse.