Skip to main content
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.

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. You will need to copy two keys from your Stripe dashboard:
  • Publishable Key — starts with pk_live_ (or pk_test_ for testing).
  • Restricted API Key (recommended) — starts with rk_live_ (or rk_test_). Shoppex also accepts a secret key (sk_live_ or sk_test_), but an unrestricted key is not required.
Both are in the Stripe Dashboard at Developers → API keys.

Create the restricted key

Stripe has a key template for third-party applications. It sets the permissions for you.
  1. In Stripe, open API keys and click Create restricted key.
  2. Select Providing this key to a third-party application and continue.
  3. Enter Shoppex as the name and https://shoppex.io as the URL.
  4. Leave Customize permissions off. Create the key.
  5. Copy the key now and keep it safe. Stripe shows a live restricted key only once.
  6. Open the key’s ⋯ menu and click Edit key.
  7. In the Connect group, set Accounts to Read. Save the change.
The template gives the key every permission that Shoppex uses, except Connect → Accounts: Read. Shoppex uses that permission only to read your own account ID. Shoppex does not use Stripe Connect.

Connecting

  1. Open Settings → Payment gateways → Card and click Connect on Stripe.
  2. Paste the Restricted API Key and Publishable 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 the shared checkout.shoppex.io and embed.shoppex.io hosts and any verified custom domain you have connected as Stripe payment method domains, for Apple Pay / Google Pay (one payment method domain covers every Stripe wallet, Link included). The Stripe row under Settings → Payments shows the result.

Using your own custom restricted key

If you set the permissions yourself (with Customize permissions on), grant these on the key. A Stripe Write permission includes Read for that resource.
  • Connect and one-time card checkout: Connect → Accounts: Read, plus Write for Webhook Endpoints, Payment Intents, Checkout Sessions, Customers, and Charges and Refunds. Stripe lists Accounts in the Connect group, under Account Links and Account Sessions.
  • Apple Pay / Google Pay domain registration: Payment Method Domains: Write. VAT tax-rate creation: Tax Rates: Write.
  • Subscription products: Write for Products, Prices, Subscriptions, Invoices, Coupons, and Customer Portal, plus Read for Setup Intents and Payment Methods.
  • Disputes: Disputes: Write, and Files: Write to upload evidence. Shoppex needs at least Disputes: Read to verify a dispute that Stripe reports before it records it on the order.

Common pitfalls

  • “Stripe API key is missing the “Accounts: Read” permission.” The key cannot read your Stripe account. Stripe’s template for third-party applications does not include this permission. Edit the key in Stripe, open the Connect group, set Accounts to Read, and connect again. Setting the Core group to Read does not cover it.
  • “Stripe API key must allow Shoppex to create webhook endpoints.” The key is missing Webhook Endpoints: Write. Create a new key as in Create the restricted key, or add the permission to your custom key. Then connect again.
  • Apple Pay domain registration fails. Stripe still connects, but Apple Pay is unavailable on the rejected domain. The Stripe row under Settings → Payments names the domain and the reason. A key from the template has the permission. On a custom key, grant Payment Method Domains: Write in Stripe, then click Retry on that row. You do not need to paste the key again.
  • Apple Pay / Google Pay missing in the embed on your own site. Add that site’s domain in Stripe → Settings → Payment method domains for Apple Pay / Google Pay. Shoppex does not know that host, so it cannot register it for you.
  • Test keys vs. live keys. Shoppex accepts restricted and secret keys in both modes. Test keys (rk_test_ or sk_test_) only accept test cards at checkout. Use them for sandbox runs, since no real money moves. Switch to live keys 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 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.

Webhooks

Shoppex creates the webhook in your PayPal app when you click Connect. You do not add one yourself. Through it, Shoppex receives disputes, refunds and reversals that happen in PayPal, and subscription renewals and cancellations.
  • PayPal allows 10 webhooks per app. If your app already has 10, Connect fails with a message. Delete a webhook you no longer use in the PayPal Developer Dashboard, then connect again.
  • If your app has a webhook to https://api.shoppex.io/v1/paypal/webhook or /v1/paypal/webhook/subscriptions from an older setup guide, Shoppex removes it. Those URLs do not work for your own app.
  • Do not delete the webhook Shoppex created (its URL starts with https://api.shoppex.io/v1/paypal/webhook/merchant/). Without it, disputes and refunds made in PayPal do not reach Shoppex. To create it again, connect PayPal again.
  • When you connect the same app again, for example after you change its secret, Shoppex keeps its webhook. When you disconnect PayPal or connect a different app, Shoppex deletes the old webhook.

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.
  • “Your PayPal app already has 10 webhooks.” Delete a webhook you no longer use in your app’s Webhooks list in the PayPal Developer Dashboard, then click Connect again.
  • 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 not API-based: Shoppex sees payments through PayPal’s IPN, or through email forwarding as an alternative to IPN.

What you will need

  • A PayPal account that can receive Friends & Family payments, and its email.
  • For IPN: the IPN settings in that PayPal account. For email forwarding: the Gmail inbox that gets PayPal’s payment emails.

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. Under Choose how Shoppex sees payments, keep IPN (the default) or pick Email forwarding.
  4. Click Connect PayPal F&F.
With IPN, 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 or email forwarding, F&F orders stay pending and need manual verification. To set up IPN:
  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 sending an IPN for each F&F payment. Shoppex matches each IPN to a pending invoice by the invoice ID in the buyer’s payment note. If your PayPal account shows no IPN settings, pick Email forwarding instead.

IPN not arriving?

The PayPal F&F dialog shows whether PayPal’s IPNs reach Shoppex. Until the first one arrives it says Waiting for first IPN; after that, IPN working and when the last IPN came. Every IPN counts, also one for a payment Shoppex did not complete (a Goods & Services payment, a wrong amount). If a buyer says they paid and no IPN for that order arrives within 15 minutes, the order timeline and your notifications say No PayPal notification received for this payment yet. The order stays as it is: check the payment in PayPal and confirm the order by hand. When no IPN arrives:
  • Check PayPal’s IPN History. In PayPal, open Account Settings → Website Payments → Instant Payment Notifications → IPN History (or paypal.com/merchantnotification/ipn/history). No entry for the payment means PayPal did not send it: the IPN settings are off or saved on another account. Entries marked Retrying or Failed mean PayPal sent it to another URL; it must be https://paypal-ff.myshoppex.io.
  • Same PayPal account as the receiver. PayPal sends the IPN from the account that receives the money. Set up IPN in the account whose email you entered in Shoppex, not in a second PayPal account.
  • Region and account type. Some PayPal regions and account types show no IPN settings. If the IPN History stays empty after a test payment to this account, pick Email forwarding instead.

Email forwarding instead of IPN

PayPal emails you for every payment; Gmail passes that email on to Shoppex. Shoppex uses one method at a time, and IPN stays the default.
  1. After connecting with Email forwarding, copy the Forward to address ({shop-id}[email protected]) and the Gmail filter (from:[email protected] OR from:[email protected]) from the dialog.
  2. In Gmail, open Settings → See all settings → Forwarding and POP/IMAP, click Add a forwarding address and paste the Shoppex address. Google sends a confirmation code; the dialog shows it within a few seconds.
  3. Open Filters and Blocked Addresses → Create a new filter, paste the Gmail filter into Has the words, click Create filter, tick Forward it to and pick the Shoppex address.
  4. No test payment is needed. Once Google’s confirmation email reaches Shoppex, the dialog says Matching on and buyers see PayPal F&F at checkout. Before that, checkout leaves it out.
If you switch from IPN to email forwarding on the same PayPal account, PayPal F&F stays at checkout and the IPN keeps paying orders until the first PayPal email comes through the forward. If a buyer says they paid and no PayPal email reaches Shoppex within 30 minutes, the PayPal F&F row shows Check your forwarding: check the Gmail filter, and confirm that order by hand once you see the money in PayPal. Shoppex completes an order from a forwarded email only when the email is PayPal’s own payment email to the PayPal email you connected, sent as Friends & Family, for the exact amount and currency of the order. Each PayPal transaction counts once, whether it arrives by IPN or by email. A payment without an order ID in the note, or to another PayPal account, appears under Unmatched payments; a short amount, another currency or a Goods & Services payment opens a payment case on the order. None of them completes the order. Changing the PayPal email or the method starts the forwarding steps over.

Held payments

PayPal sometimes holds a payment for a few days before you can use it. By default the order waits until PayPal releases the money, and the order timeline shows PayPal is holding the payment. Turn on Complete orders on held payments to complete the order as soon as PayPal reports the payment. A held payment can still be reversed, so with this on a buyer could keep the item without paying. The switch applies to IPN and email forwarding alike.

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.
  • The invoice ID they need to include in the PayPal note field, exactly as shown (no prefix).
The buyer pays out-of-band on PayPal. PayPal sends the IPN to Shoppex, or Gmail forwards PayPal’s payment email. 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 payment 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}[email protected]. 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:[email protected] OR from:[email protected] 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.

MisticPay (PIX)

Brazil-only. PIX is Brazil’s instant bank transfer system; MisticPay is the processor that issues the PIX charge and confirms the transfer. Buyers pay from their own bank app by scanning a QR code or pasting a “Pix Copia e Cola” code.

What you will need

  • A verified MisticPay account (MisticPay requires a Brazilian CPF or CNPJ during KYC).
  • BRL as the currency of the products you sell with PIX. The method is only offered on invoices priced in BRL.

Connecting

  1. In the MisticPay dashboard open API → Credenciais and click Gerar credenciais.
  2. Grant both permissions: Gerar transação and Verificar transação. Shoppex confirms every payment with the second one before it completes an order.
  3. Open Settings → Payment gateways → Platforms → Connect on MisticPay (PIX).
  4. Paste the Client ID and Client Secret and click Connect.
No webhook setup is needed. Shoppex attaches its own webhook URL to every PIX charge it creates. The URL is shown in the wizard once connected in case you want to add it as an account-level webhook in MisticPay as well.

Buyer flow

  1. The buyer selects PIX at checkout and enters their full name and CPF. MisticPay requires both for every charge; Shoppex validates the CPF check digits and stores only its last two digits.
  2. Shoppex creates the charge and shows the QR code and the copy-and-paste code.
  3. The buyer pays in their bank app. The order completes automatically once MisticPay confirms the transfer, usually within seconds.

Common pitfalls

  • BRL only. If the invoice is not priced in BRL, PIX does not appear in the checkout.
  • Missing permission. Without Verificar transação Shoppex cannot confirm payments, so charges stay pending. Regenerate the credentials with both permissions and reconnect.
  • Wrong CPF. A charge is bound to the payer the buyer entered. The buyer can change the payer details in the checkout, which creates a new charge; the old one simply expires unpaid.

Skinloop (CS2 and Rust skins)

Buyers pay a USD order with Counter-Strike 2 or Rust skins from their Steam inventory. The trade happens on Skinloop’s hosted checkout; the value lands in your Skinloop balance.

What you will need

  • A Skinloop merchant account.
  • USD as the currency of the products you sell with skins. The method is only offered on orders priced in USD.

Connecting

  1. Open Settings → Payment gateways → Card → Connect on Skinloop. The wizard shows a Webhook URL and a Redirect Origin.
  2. In Skinloop open API & Webhooks, add the webhook URL and subscribe to payment.pending, payment.completed and payment.reverted. Skinloop shows the signing secret (whsec_…) once. Paste it into the wizard.
  3. In Skinloop open Checkout Configuration → Checkout Redirect Origins and approve the redirect origin. Buyers return to your checkout through it.
  4. In Skinloop create an API key with the scopes checkout:create and checkout:read, for the games you want to accept. Paste it into the wizard.
  5. Turn on the games buyers may pay with and click Connect. Shoppex checks the key with Skinloop before it saves.

Buyer flow

  1. The buyer selects Steam Skins at checkout and is sent to Skinloop, where they pick skins worth at least the order total and confirm the trade in Steam.
  2. The buyer returns to the order page. The order shows as processing until Skinloop confirms the payment.
  3. Rust trades usually confirm right away. CS2 trades sit in a Steam trade hold for up to 8 days; the order completes when the hold ends and Skinloop reports the payment as completed.

Common pitfalls

  • USD only. If the order is not priced in USD, Skinloop does not appear in the checkout.
  • CS2 means waiting. Nothing is delivered during the Steam hold. If you sell instant-delivery goods, accept Rust only.
  • Quantity stock is not reserved during a hold. If the last unit sells to someone else while a CS2 trade is held, the order waits for a restock after it is paid. Serials an order reserved stay locked for the whole hold (see Reserved stock below).
  • No refunds from Shoppex. Skinloop has no refund API. A payment Skinloop reverses on its own shows as refunded on the order.
  • Wrong scopes or games on the key. The check before saving confirms which Skinloop account the key belongs to, not its scopes. A key without checkout:create, or without a game you turned on, connects but cannot open a checkout; a key without checkout:read cannot confirm payments. Create a new key in Skinloop and save it in the wizard.
  • Disconnecting stops new checkouts only. Checkouts that are already open and trades in a hold still complete. Shoppex keeps the key and signing secret encrypted for those payments, so leave the key and the webhook active in Skinloop until they have settled.
  • Reversals after you disconnect. Skinloop can reverse a completed payment later. Shoppex keeps the key and signing secret of that Skinloop account encrypted for 90 days after a payment completed, also after you disconnect or connect another account, only to verify such a reversal and mark the order refunded. Keep the webhook and the key active in Skinloop for that time.
  • Rotating a key. Save the new key in the wizard before you revoke the old one in Skinloop. Shoppex then reads every earlier payment of that account with the new key.
  • Revoking a key with open payments. If you revoke the key in Skinloop while a checkout is open or a trade is in a hold, Shoppex can no longer confirm that payment. The order stays open and keeps its reserved stock until you save a working key or support closes it.
  • Reserved stock. An order that reserves serials gives its Skinloop checkout two hours instead of 24. The stock is released only after Skinloop confirms the checkout expired.

VenPayr (cards)

Buyers pay by card on VenPayr’s hosted checkout. VenPayr charges the buyer its own card fee on top of the order.

What you will need

  • A VenPayr store with card payments approved by VenPayr.
  • The store API key from Settings → Store API Key in VenPayr.

Connecting

  1. Open Settings → Payment gateways → Card → Connect on VenPayr.
  2. Paste the store API key and click Connect. Shoppex checks the key with VenPayr before it saves.
No webhook setup is needed. Shoppex sends its own webhook URL with every checkout and verifies each delivery with your API key.

Buyer flow

  1. The buyer selects VenPayr at checkout. Before leaving your checkout, the buyer sees VenPayr’s card fee and the total VenPayr will charge.
  2. The buyer pays on VenPayr’s page and returns to the order page.
  3. The order completes when VenPayr confirms the payment, by webhook or when the buyer returns.

Common pitfalls

  • **Orders under $3.** VenPayr refuses checkouts below a $3.00 equivalent, so VenPayr does not appear in the checkout for them. A minimum you set under Fees & limits applies on top.
  • The card fee is not your revenue. VenPayr’s fee (1.79% + $0.79, plus any extra fee you set in VenPayr) is paid by the buyer to VenPayr. The order total in Shoppex stays the price of the order.
  • Card payments pending review. Until VenPayr approves card payments for your store, VenPayr quotes no card fee and refuses card checkouts. Keep VenPayr disabled until the approval.
  • Rotating the key. A new key in VenPayr stops the old one at once. Paste the new key into the wizard right away; until then new checkouts fail and webhooks for open checkouts cannot be verified.
  • Disconnecting. Disable VenPayr first and wait 30 seconds. Shoppex refuses the disconnect while a VenPayr checkout may still have been paid (open, or created within the last 30 hours and not settled), because it needs your key to confirm that payment.

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

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.
For multi-coin coverage beyond BTC/LTC, connect a provider (Cryptomus / Oxapay) instead. See 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.