# Payment Gateways

## Overview

Payment Gateways (Admin → Payment gateways) is where you turn on the payment methods your customers use to pay for subscriptions and credits. WaDesk ships with 30 gateways covering cards, wallets, bank transfer, crypto, and dozens of regional methods.

Every gateway is already listed, so there is no "install" step. For each one you open its card, enter its credentials, pick sandbox or live, choose which currencies it accepts, and switch it on. Credentials are encrypted when stored, secrets are never shown back in plain text, and customers only ever see gateways that accept their currency.

On each card you can:

- Save the credentials, mode (sandbox/live), display order, and accepted currencies. Every save is recorded in the audit log.
- Activate or deactivate the gateway — you cannot activate until its required fields are filled in (see below).

## The Gateway Catalog

Each gateway is a collapsed card — only the header row (name, status, mode badge, region tags) shows until you click it open, then the credentials form expands in place. A stats strip up top counts total gateways, how many are Active, the number of India-region options, and Crypto options.

The five "top" gateways are fully implemented and tested; the remaining 25 round out the global catalog. A sample of what's available:

Gateway | What it accepts
--- | ---
Stripe | Cards (Visa/MC/Amex), Apple Pay, Google Pay — global. Uses Stripe Checkout Sessions.
Razorpay | Indian cards, UPI, netbanking, wallets, EMI. Standard Checkout modal.
PayPal | Worldwide PayPal balance + cards via PayPal Checkout (Orders v2).
Paddle | Merchant-of-record for SaaS — cards + global tax handling.
Mollie | European cards, iDEAL, Bancontact, SEPA, Klarna.
Paystack / Flutterwave | Africa — cards, bank, USSD, mobile money.
Coinbase Commerce | Crypto — BTC, ETH, USDC, DAI, LTC, BCH.
Bank Transfer / Offline | Show your bank details or mark orders paid manually (for enterprise quotes). No credentials required.

The full set also includes Square, Braintree, 2Checkout, Mercado Pago, iyzico, Authorize.Net, SSLCommerz, Instamojo, PhonePe, Cashfree, PayU, Midtrans, Xendit, Tap, HyperPay, PayTR, Fondy, Skrill, and CinetPay.

## Category Tabs & Currency Badges

Thirty drivers in one list would be unwieldy, so the page groups them into category tabs. Click a tab to filter the cards; each tab shows a live count. A gateway can belong to several tabs, and its first few categories appear as small badges on its card header.

Tab | Covers
--- | ---
All | Every gateway available.
Popular | Stripe, PayPal, Razorpay, Paddle, Square, Braintree, Mollie, Authorize.Net.
India | Razorpay, Instamojo, Cashfree, Paytm, PhonePe, PayU.
Asia | Xendit, Midtrans, Paytm, PhonePe, SSLCommerz, HyperPay, Tap.
MENA | HyperPay, Tap, PayTR, iyzico, Fondy.
Europe | Mollie, Paddle, Stripe, PayTR, iyzico, Fondy.
US / CA | Stripe, PayPal, Square, Braintree, Authorize.Net, 2Checkout.
Africa | Paystack, Flutterwave, CinetPay.
LATAM | Mercado Pago.
Crypto | Coinbase Commerce.
Offline | Bank transfer / cash on delivery.

A search box below the tabs filters by gateway name or slug, so you can jump straight to the one you need. Each card header also carries two status badges: Active / Disabled and a mode badge (amber sandbox or coral live), plus a Keys saved badge once credentials are on file.

Currencies are handled by a pill-grid picker inside each card: each active currency is a clickable pill, selected pills turn solid, and the count of selected currencies is shown live. The selection is the gateway's supported currencies whitelist — leave it empty to accept every currency. At checkout a workspace only sees gateways whose whitelist is empty or contains the order's currency.

## Configuring a Gateway

Open a gateway card and you'll see a credentials form showing only the fields that gateway actually needs. Each field has a label, a required marker, and often a hint about the value's format. Fill them in, set the other options, and click Save.

Below the credentials, every card has the same three controls:

Setting | What it does
--- | ---
Mode | Sandbox or Live. Sandbox uses the gateway's test environment so you can verify the flow without real money. (PayPal, for example, switches its API base between `api-m.sandbox.paypal.com` and `api-m.paypal.com` based on this.)
Sort order | Controls the order gateways appear in at checkout (lower first).
Supported currencies | The pill-grid whitelist. None selected = accept all. Workspaces only see gateways that accept their currency.

> Note — leave blank to keep: A saved secret is never shown back in the page; the field stays empty with a `•••••••••• (saved — leave blank to keep)` placeholder. On save, a blank secret keeps the stored value — only typing a new value overwrites it. So you can change mode or currencies without re-typing your keys.

## Credential Fields for the Major Gateways

For the big three, here is exactly where to GET each value from the provider's dashboard and which WaDesk field to PASTE it into. Required fields are marked with an asterisk and must be present before the gateway can be activated.

### Stripe

Get all three values from the Stripe Dashboard at dashboard.stripe.com/apikeys (and the Webhooks page for the signing secret). Toggle View test data in the dashboard to get `test` keys for sandbox.

WaDesk field | Where to get it
--- | ---
Publishable key | Stripe → Developers → API keys → Publishable key (`pk_live_…` / `pk_test_…`).
Secret key * | Same page → Secret key (`sk_live_…` / `sk_test_…`). Reveal once and copy.
Webhook secret | Stripe → Developers → Webhooks → add an endpoint pointing at your WaDesk webhook URL (see below) → copy the Signing secret (`whsec_…`). Lets WaDesk verify that webhook calls really came from Stripe.

### Razorpay

Get the key pair from the Razorpay Dashboard at dashboard.razorpay.com/app/keys (Settings → API Keys → Generate Key). Use the Test Mode switch for sandbox keys.

WaDesk field | Where to get it
--- | ---
Key ID * | API Keys page → Key Id (`rzp_live_…` / `rzp_test_…`).
Key secret * | Shown once at generation as Key Secret. Copy immediately.
Webhook secret | Dashboard → Settings → Webhooks → create a webhook to your WaDesk URL and set a secret; paste that same secret here. Lets WaDesk verify that webhook calls really came from Razorpay.

### PayPal

Get the credentials from the PayPal Developer Dashboard at developer.paypal.com/dashboard/applications → Apps & Credentials. Switch between the Sandbox and Live tabs to match your WaDesk Mode, then open your app.

WaDesk field | Where to get it
--- | ---
Client ID * | Your REST app → Client ID.
Client secret * | Same app → Secret (click to reveal / generate).

> All other gateways follow the same shape — open the card to see its exact fields, each with a hint. Common patterns: Mollie uses an API key, Coinbase Commerce uses an API key plus a webhook shared secret, Paystack/Flutterwave use a public and a secret key, Authorize.Net uses a login ID and transaction key, and Bank Transfer / Offline need no credentials at all.

## Webhook & Callback URLs to Register

WaDesk exposes one webhook endpoint and one return/callback endpoint per gateway, both keyed by the gateway slug. Register these at the corresponding provider so payments confirm reliably even if the customer closes the tab.

Purpose | URL to register at the provider
--- | ---
Webhook (async server-to-server notification, `POST`) | `https://YOUR-DOMAIN/payment/webhook/{gateway}`
Return / callback (browser redirect after pay, `GET` & `POST`) | `https://YOUR-DOMAIN/payment/callback/{gateway}`

Replace `{gateway}` with the gateway's short name (shown as `slug: …` on each card). Concrete examples:

Gateway | Webhook URL | Register at
--- | --- | ---
Stripe | `https://YOUR-DOMAIN/payment/webhook/stripe` | Stripe → Developers → Webhooks → Add endpoint. Then copy its signing secret into the Webhook secret field.
Razorpay | `https://YOUR-DOMAIN/payment/webhook/razorpay` | Razorpay → Settings → Webhooks. Set the same secret you put in the Webhook secret field.
PayPal | `https://YOUR-DOMAIN/payment/webhook/paypal` | PayPal Developer → your app → Webhooks. (PayPal confirms the payment on the return; the webhook is optional reinforcement.)
Coinbase Commerce | `https://YOUR-DOMAIN/payment/webhook/coinbase` | Coinbase Commerce → Settings → Webhook subscriptions.

The webhook URL is intentionally open (gateways can't log in) but WaDesk verifies each call's signature against the webhook secret you saved, so only genuine calls from the provider are accepted. If no webhook secret is set, the check is skipped (fine in sandbox, but always set a secret before going live).

> Note: The return/callback URL is what WaDesk hands the gateway as the success URL during checkout, so it usually doesn't need manual registration. The webhook URL is the one you paste into the provider's dashboard, and for Stripe/Razorpay it must be paired with the matching webhook secret in WaDesk.

## Activating, the Required-Fields Guard & Sandbox vs Live

Each gateway has an Activate / Disable button in its card header. Activating makes the gateway available at checkout; deactivating removes it.

> Guardrail — required fields before activate: You cannot activate a gateway until its required fields (those marked *) are filled in. If you try, activation is refused with a message listing the missing fields — for example "Configure required fields first: Secret key" — and the blocked attempt is recorded in the audit log. This stops a half-configured gateway from appearing at checkout and failing on the customer's first payment.

Recommended path for any new gateway:

1. Get your test/sandbox credentials from the provider (use its test-mode switch) and paste them into the card.
2. Register the webhook URL in the provider's test environment and paste the resulting signing secret into the Webhook secret field.
3. Set Mode to Sandbox, save, and Activate.
4. Run a test checkout to confirm the full flow works end to end.
5. Swap in your live credentials and the live webhook secret, switch Mode to Live, and save.

> Caution: Always confirm you've switched to Live mode before announcing a gateway to customers — a gateway left in Sandbox will accept test cards but never settle real money. The card's mode badge turns coral when it is Live.

## Security & Auditing

Credentials are encrypted when stored and are never shown back in plain text in the form.

Every change is written to the audit log — but never the secret values themselves. On save, the log records which fields were updated, the chosen mode, and the supported currencies. Activations, deactivations, and blocked-activation attempts (with the list of missing fields) are all recorded too, so you have a full history of how your payment setup evolved.

> Caution — after a server encryption-key change: Credentials are encrypted with your app's master encryption key. If that key is ever changed (a server-level maintenance task), the previously stored credentials can no longer be read. After any such change, re-enter the credentials for every active gateway.

## Troubleshooting

Symptom | Likely cause & fix
--- | ---
"Configure required fields first: …" | You tried to activate before filling a required (*) field. Open the card, complete the listed fields, save, then activate.
Webhook not received | The URL registered at the provider is wrong or unreachable. Confirm it is exactly `https://YOUR-DOMAIN/payment/webhook/{gateway}` over HTTPS, that the domain is publicly reachable, and that it's registered in the matching environment (test vs live). Check the provider's webhook delivery/log panel for the response code.
Signature mismatch | The webhook secret in WaDesk doesn't match the one set at the provider, or you're verifying a test webhook against a live secret. Re-copy the signing secret (Stripe `whsec_…` / your Razorpay webhook secret) and make sure Mode matches the keys.
Currency unsupported / gateway missing at checkout | The order's currency isn't in the gateway's Supported currencies list. Either add the currency pill, or clear the list to accept all. Also confirm the gateway is Active.
"Secret key missing" error from a gateway | The required secret was never saved, or was lost after a server encryption-key change. Re-paste it. Remember a blank field keeps the old value — if the old value is gone, you must type a fresh one.
Payment succeeds at the gateway but order stays unpaid | The return or webhook didn't reach WaDesk (tab closed early, webhook misconfigured). Fix the webhook URL/secret so the confirmation lands; WaDesk can also reconcile a late confirmation.
Live mode charges fail but sandbox worked | You're still using test keys, or you updated the keys but left Mode on Sandbox (or vice-versa). Make sure live keys, Live mode, and the live webhook secret are all set together.
No gateways listed at all | The gateway catalog didn't load. Ask your support team to re-run the install setup to restore the gateway list.

## Related Pages

- AI & API Keys — the same pre-seeded, encrypted, leave-blank-to-keep credential pattern, applied to AI providers.
- Security & Audit Log — where gateway saves, activations, and blocked attempts are recorded.