Payment gateways

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.

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.

​

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 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 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}[email protected]. Copy it.

​

Set up Gmail forwarding

1. Open Gmail → Settings → Forwarding and POP/IMAP → Add a forwarding address.
2. Paste the Shoppex forwarding address.
3. Gmail sends a verification code to that address. Shoppex auto-captures the code — go back to the Cash App wizard, click Verify, and it’ll show the code.
4. In Gmail, also create a filter: from [email protected] → forward to the Shoppex address and (optionally) mark as read.

Step 3 of the wizard confirms forwarding is working — you should see a green check.

​

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.
• Setup not complete = can’t enable. All three pieces (cashtag, your Gmail, forwarding verified) must be in place. If any is missing, the enable toggle stays disabled and shows “Connect Cash App before enabling it.”
• 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 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 → 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: Direct wallets

For settling specific coins directly to wallets you own — no intermediary. Four direct chains are supported. For each, you paste an address and Shoppex routes payments straight there.

• Bitcoin — paste a BTC address.
• Litecoin — paste an LTC address.
• Ethereum — paste an ETH address.
• Bitcoin Lightning — paste a Lightning Address (preferred — looks like [email protected]) or an LNURL endpoint.

​

Setup

Settings → Payment gateways → Crypto → Connect on the coin you want. Paste the address, save. Activate the toggle. It’s live.

​

Common pitfalls

• Wrong address format. Shoppex validates against the coin’s expected pattern, but if you paste an SegWit address into the Legacy BTC field (or vice versa), some buyers’ wallets may not handle it. Stick with one address type.
• Lost address = lost funds. Direct wallets are non-custodial. If you lose access to the wallet’s private key, Shoppex has no way to recover funds sent there.
• No automatic refunds. Since Shoppex doesn’t custody the wallet, crypto refunds via direct addresses are manual — you send the funds back yourself from your wallet, then mark the order refunded in Shoppex. See Refunds.