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

> ## Agent Instructions
> OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees.
> Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown.
> OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis.
> MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries.
> Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix.
> Plugin development: consult /developer/plugins/ pages for correct interfaces and manifests.
> Canonical locations: API auth = /api/authentication, webhook verification = /api/webhooks, rate limits = /resources/rate-limiting, transaction statuses = /fundamentals/payment-flow.
> The documentation uses the Diataxis framework: Tutorials (learning), How-to (tasks), Reference (lookup), Explanation (understanding).

# Configure payment gateways

> How to add, configure, test, and activate API-based payment gateways in OwnPay with encrypted credential storage.

Payment gateways are the processors that actually move money - Stripe, PayPal, bKash, Nagad, and over 100 others. You configure them once in OwnPay and then assign them to brands so they appear at checkout.

## Add a gateway

1. Go to **Gateways & Currencies** → **Payment Gateways**.
2. Click **+ Add Gateway**.
3. Select the provider from the list (for example Stripe, bKash API, Razorpay).
4. Enter the required credentials (see table below).
5. Click **Save**.

## Enter credentials

Each gateway requires different credentials depending on the provider. Common fields include:

| Field              | Description                                      |
| ------------------ | ------------------------------------------------ |
| **API key**        | Public or secret key from your gateway dashboard |
| **API secret**     | Secret key or token for authentication           |
| **Merchant ID**    | Your merchant identifier at the gateway          |
| **Webhook secret** | HMAC signing key for verifying incoming webhooks |
| **Sandbox mode**   | Toggle to use the gateway’s test environment     |

<Note>
  All credentials are encrypted at rest using **AES-256-GCM**. They are never stored in plaintext in the database. Only the OwnPay application can decrypt them using the server-side encryption key.
</Note>

## Gateway settings reference

| Setting                | Type         | Description                                            |
| ---------------------- | ------------ | ------------------------------------------------------ |
| **Min amount**         | Number       | Minimum transaction amount this gateway will accept    |
| **Max amount**         | Number       | Maximum transaction amount this gateway will accept    |
| **Allowed currencies** | Multi-select | Which currencies this gateway supports for checkout    |
| **Status**             | Toggle       | Active (available at checkout) or Inactive             |
| **Sandbox mode**       | Toggle       | Route payments through the provider’s test environment |

## Test with sandbox mode

Before going live, enable **Sandbox mode** on the gateway and run a test payment:

1. Set **Sandbox mode** to **On**.
2. Set the gateway status to **Active** and assign it to a brand.
3. Create a test payment link and complete a checkout.
4. Verify the transaction appears in **Payments** → **Transactions** with **Completed** status.
5. Once confirmed, disable Sandbox mode.

## Activate per brand

Configuring a gateway makes it available globally, but it only appears at checkout when you assign it to a brand:

1. Go to **People** → **Brands** and edit the target brand.
2. In the **Gateways** section, toggle the gateway on.
3. Only gateways that support the brand’s currency are eligible.

## Common issues

| Problem                                   | Cause                                                   | Solution                                                                                |
| ----------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Invalid credentials** error at checkout | Wrong API key or secret copied                          | Re-check the keys in your gateway provider dashboard and paste them again               |
| Transactions stay Pending                 | Webhook URL not configured at the gateway provider      | Add your OwnPay webhook endpoint (`/webhook/{gateway-slug}`) in the gateway’s dashboard |
| Gateway not showing at checkout           | Gateway not assigned to the brand, or currency mismatch | Edit the brand and enable the gateway; verify the gateway supports the brand’s currency |
| Sandbox payment fails                     | Sandbox keys differ from live keys                      | Make sure you are using the sandbox/test keys, not your production keys                 |

<Warning>
  Never commit API keys to version control or share them in chat. All credential management happens through the OwnPay admin UI or encrypted environment variables.
</Warning>

## Related Pages

* [Manual methods](/docs/gateways/manual-methods) - configure offline payment methods
* [Currencies](/docs/gateways/currencies) - manage currencies and exchange rates
* [Brands](/docs/people/brands) - assign gateways to brands
* [SMS verification](/docs/gateways/sms-verification) - auto-verify manual payments
* [Webhooks](/docs/api/webhooks) - configure webhook endpoints


## Related topics

- [Manual payment methods](/docs/gateways/manual-methods.md)
- [Manage currencies and exchange rates](/docs/gateways/currencies.md)
- [Gateway Plugin Development - Build Custom Payment Gateways](/docs/developer/plugin-types/gateway.md)
- [WooCommerce Plugin - Accept Payments on WordPress](/docs/developer/integration/woocommerce.md)
- [WHMCS Integration](/docs/developer/integration/whmcs.md)