> ## Documentation Index
> Fetch the complete documentation index at: https://andcze.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Payment Providers
> Add and set up payment gateways so your customers can pay in your shop.
For customers to be able to buy items in your shop, you need to connect at least one payment provider (that is, a gateway that takes the money — for example BLIK, a card, or a bank transfer). On this page you set up who handles payments and which methods the buyer sees when finishing an order.
You'll find this section in the side menu, in the **INTEGRATIONS** group, under the name **Payment Providers**. In the panel itself the page heading says "Payment Methods" — it's the same thing.
## List of providers
Your providers are shown as a **grid of cards** — each card is one provider. On the card you can see the most important information right away:
* The **provider's logo** on a light bar at the top (if a provider has no logo, its name appears in its place instead).
* A **status badge** in the top-right corner of the card — **Active** (green), **Inactive** (grey), or **Disabled** (when you've manually switched off the gateway).
* The **display name**, and below it the provider's **category** (e.g. "Online Transfers", "BLIK", "Payment Cards") with a small coloured dot.
* **Extra badges**: **Test mode** (when it's turned on), the **currency** (e.g. `PLN`), and **Fee X%** (if you've set a shop fee).
A provider can be **Active**, **Inactive**, or **Disabled**. "Active" means customers can pay with it. "Inactive" appears when you switch it off with the toggle on the list. "Disabled" is the state when you turn on the "Disable payment gateway" option in the provider's settings.
### Buttons on a provider card
At the bottom of each card you'll find a set of buttons:
Opens the full provider configuration screen (with the tabs described below), where you can change every setting.
A shield-icon button that checks whether all required fields are present. It does not validate credentials with the provider or confirm channel availability; verify those in the sandbox and with an end-to-end signed-webhook test.
With a single click you can activate or temporarily deactivate a provider, without removing it from the list.
A trash-can icon. A confirmation prompt appears — the provider is only removed after you click **Delete**. This can't be undone.
After every change to the keys, it's worth clicking **Check configuration**. If you see the message "Missing configuration fields" along with a list of fields — go back to the **Configuration** tab and fill in those details. This eliminates the most common reason payments don't work.
### Reordering providers
When you have more than one provider, you can set their order. **The order of the cards = the order in which the providers appear for the customer when finishing an order.** Above the list you'll see a hint saying the same thing.
You change the order using the **arrows** in the top-left corner of the card (left = earlier, right = later). The change is saved straight away.
Put your most popular provider (e.g. one that handles BLIK) first — the customer will spot it faster, and you'll increase the chance the purchase gets completed.
### When you don't have any providers yet
If you haven't added any provider yet, you'll see the message **"No payment methods"** with an encouragement to add your first provider. This is normal at the start — just click **Add provider** and go through the setup.
If you work in a team, only people with the right permissions will see the buttons for adding, managing, and deleting. A teammate without permissions will see the list, but won't be able to change it.
## Adding a provider
Click the **Add provider** button in the top-right corner. A simple flow opens: first you choose a provider, then you set it up.
You'll see a grid of providers with their logos. At the top there's a **search box** ("Search for a provider…") and **category filters** in the form of clickable badges (e.g. "All", "Online Transfers", "BLIK", "Payment Cards", "Online Payments"). Next to each category you can see the number of providers that belong to it. Click the card of the provider you want to add.
After choosing a provider you'll move to a screen with tabs. At the top you'll see the provider's logo and name, and if you don't have an account with them yet — a link **"Don't have an account with this provider? Create an account"**, which opens their site in a new tab. Next to it there's also a **"Change provider"** link, in case you change your mind.
Once all required details are present, click **Add provider**. It appears on the list. Before exposing it to buyers, verify the credentials in the sandbox, a signed webhook, and end-to-end delivery of a test product.
Before you start, create an account with the provider and have your access details from their panel ready. Without them you won't be able to finish the setup. If you don't know where to register, use the **"Create an account"** link shown on the setup screen.
If no results match what you type into the search box, you'll see the message "No results". Clear the search with the cross, or pick a different category to see the full list.
## Configuration tabs
The provider configuration screen (both when adding and later via **Manage**) is split into six tabs. You can switch between them freely.
Set the **display name** and the **default currency** in which payments are settled.
Paste the **keys and access details** copied from the provider's panel. They're what connect your shop to the gateway.
Choose which **payment methods** (e.g. BLIK, card, Przelewy24) the customer sees, and set their **order**.
Here you'll find the **notification address (webhook)** that you need to paste into the provider's panel so it informs your shop about paid orders.
Set the **provider fee** and the **shop fee**, set amount limits, and decide who covers the payment cost.
Turn **test mode** on or off, **disable the whole gateway**, and use extra behaviour toggles.
If an error appears in one of the tabs when saving (e.g. a required field is missing), the panel **automatically takes you to the right tab** and highlights the field to fix. That way you don't have to hunt for where the problem is.
### General settings
These are the basic details about the provider:
* **Provider** — the gateway choice. When adding, you pick it from the list (if you didn't already do so in the grid). **Once a provider is created, the gateway can no longer be changed** — when editing, the field is read-only.
* **Display name** — the provider's label that you see in the panel (e.g. "Quick transfer"). It makes the provider easier to recognise when you have several. This field is **required**.
* **Default currency** — the currency in which payments will be settled. The list shows **only the currencies supported by the chosen provider**. If a provider supports only one currency, you'll see a note about that.
Want to switch to a different provider? You can't do it within an existing configuration — delete it and add a new one. That's why, when adding, it's worth choosing the right gateway straight away.
### Configuration
Here you paste the **access details (API keys)** that you'll find in your provider's panel. They're what lets the shop work securely with the gateway.
* Each provider has its **own set of fields** — e.g. shop ID, service key, secret key. The panel will show exactly the fields the chosen provider requires.
* Fields with keys and passwords are **masked** (like a password), so no one can read them over your shoulder.
* Some providers also have a **toggle** (e.g. sandbox mode) — in that case, instead of a text field you'll see a switch.
* Fields marked with an asterisk are **required** — without them you can't save the provider.
Keep your access details (keys) secret. Don't share or send them to anyone — they let payments be taken in your name, so they work like a password to your money.
If the chosen provider doesn't require any extra keys, you'll see the message **"This provider doesn't require additional API keys"** — in that case you simply skip this tab. And if you haven't chosen a provider yet, the panel will ask you to do that first in the "General settings" tab.
### Channels
In this tab you decide **which payment methods the customer will see** while finishing an order — for example BLIK, a card, or Przelewy24. You can:
* **enable and disable** individual channels with the toggle next to each of them,
* set their **order** by dragging the handle (the ⠿ symbol) or using the **up and down arrows**.
The order in the list matches the order in which the channels appear for the customer.
Put the most popular methods (e.g. BLIK) at the top of the list — the customer will spot them faster, and you'll increase the chance the purchase gets completed.
If a provider offers only one channel, you'll see a note that there's nothing to configure. When **adding** a new provider, channels often appear only **after it's been saved** — in that case you come back to this tab via **Manage**, turn on the channels you want, and set their order.
### Notifications
Some providers require you to paste a special **notification address (webhook)** into their panel. Thanks to it, the provider automatically informs your shop when a customer pays for an order — and the item is delivered to the player.
* You'll find the address in this tab **after adding the provider**. Next to it there's a **Copy** button — click it, copy the address, and paste it into the notification / webhook settings in the provider's panel.
* If the provider doesn't use a manually set address, you'll see a note that payment confirmations **work automatically** — in that case you don't have to do anything.
**Don't share the notification address with anyone.** It contains a secret element that allows payments to be confirmed — paste it only into your own provider's panel.
### Fee
This tab lets you set precisely how payment costs are calculated. It has two parts.
#### Payment provider fee
This is the charge the provider takes on every transaction. First you use a toggle to **turn on calculating the provider fee**. When you turn it on, extra fields appear:
* **Fee source** (for providers that support this) — **Automatic** (the fee is taken straight from the provider on every transaction, you don't have to enter anything) or **Manual** (you enter the values yourself below).
* **Fee (%)** and **Fee (amount)** — in manual mode you enter a percentage and/or a fixed fee amount.
* **Fee calculation method** — you decide whether to calculate the **percentage first, then the amount**, or the **amount first, then the percentage**.
* **Calculating the final amount for the buyer** — you choose whether the fee should be **added to the price for the buyer** (in which case the customer covers the payment cost) or **not increase the amount for the buyer** (the cost is deducted from your revenue). By default the amount for the buyer is **not** increased.
Some providers can report their actual fee themselves — for those, the "Automatic" source is available. For the rest, you enter the fee manually.
#### Shop fee and limits
The second part of the tab is additional settlement settings:
* **Shop fee (%)** — a percentage fee added to the payment on your side. Leave it at `0` if you don't want to add anything.
* **Minimum amount** and **Maximum amount** — optional limits for a single payment with this provider. Leave them empty if you don't want to restrict them.
Adding the fee to the buyer's price comes in handy when a provider charges a higher fee (e.g. SMS payments). You can then set it up so the customer covers that cost — your revenue stays the same.
### Options
Here you'll find extra toggles that control the provider's behaviour:
"Log errors when generating/receiving payments" — when turned on, any problems with this provider go to the **Errors** section, where you can review and fix them. It's worth keeping on.
Temporarily stops this provider from taking payments, without removing it from the list. On the list it then gets a **Disabled** badge.
"Allow automatic currency conversion" — lets the provider convert currencies when the customer pays in a currency other than the default.
"Block promotions on this gateway" — turns off price reductions when paying with this provider (e.g. when this method is expensive to handle).
"Block promo codes on this gateway" — with this method the customer won't be able to use discount codes.
Uses the provider's sandbox without real settlement. The method gets a **Test mode** badge and is not exposed in public checkout. An authenticated staff member can exercise sessions through the administrative payment API.
A valid sandbox callback can start delivery for the test order. Use a dedicated test product and server, then disable test mode and complete a new low-value purchase in the provider's production environment before launch.
When **adding** a new provider, the "Options" tab also has a toggle **"Add to all products at the standard price"**. When it's on (the default), the new method immediately becomes available for all your products at the base price. You can fine-tune which method to use for which product later, in the product settings (the "Payment methods" section).
## Checking the configuration
On the provider list, every card has a **Check configuration** button (the shield icon). It verifies only whether all required fields are present:
* If the fields are complete, you see **"The configuration is correct"**. This does not mean the provider accepted the credentials.
* If something is missing — the message **"Missing configuration fields"** appears along with a list of the missing fields. In that case go to **Manage → Configuration** and fill in the indicated details.
Check the configuration every time after adding a provider or changing keys. It's a few-second click that saves you from a situation where the customer pays but the payment doesn't go through.
## Managing the provider list
On the main list you can quickly organise your gateways:
* **Arrows** — change the order of providers using the arrows in the card corner. It's worth keeping the most frequently chosen gateways at the start.
* **Enable / Disable** — activate or temporarily deactivate a provider with one button.
* **Manage** — open the full configuration to change any setting.
* **Delete** — completely remove a provider you no longer use (with confirmation).
The order of providers on the list matches what the customer sees first when finishing an order.
## Frequently asked questions
"Inactive" appears when you switch a provider off with the **Disable** button on the list. "Disabled" means that in the provider's settings (the "Options" tab) you turned on the "Disable payment gateway" toggle. In both cases the customer can't pay with this provider — the only difference is where you switched it off.
Check one thing at a time: whether the provider is **Active** (not "Inactive" or "Disabled"), whether **test mode** is off, whether in the **Channels** tab you have at least one method enabled, and whether **Check configuration** isn't reporting any missing fields.
No — the gateway can't be changed after creation. If you want a different gateway, delete the current provider and add a new one.
It's an address that some providers require you to paste into their panel. Thanks to it, the provider informs your shop on its own when an order is paid, and the item reaches the player automatically. Copy it with the **Copy** button and don't share it with anyone.
You decide this in the **Fee** tab, in the "Calculating the final amount for the buyer" field. By default the fee doesn't increase the buyer's price (you cover it out of your revenue). If you choose "Add the fee to the buyer's amount", the customer bears the cost.
## Common pitfalls
Fill in **all the required fields** in the Configuration tab. A missing key is the most common reason payments don't work — click **Check configuration** to catch it.
Check the **Options** tab and make sure test mode is **off** before you start selling.
If a provider requires a webhook, then without pasting the **notification address** into its panel, your shop may not know about paid orders.
Leave at least one method enabled in the **Channels** tab, otherwise the customer won't have any way to pay.
If you turn on "Disable payment gateway" in "Options", the provider disappears from checkout even though it's on the list. Remember to turn it back on.
Check the "Minimum" and "Maximum amount" fields in the Fee tab — too narrow a range may block some orders.
## Best practices
* **A provider account first** — set it up and get your keys ready before you start the configuration. Use the "Create an account" link on the provider screen.
* **Always check the configuration** — after adding or changing keys, click "Check configuration" to be sure nothing is missing.
* **Turn off test mode before going live** — this is the most common mistake. Without it, customers won't actually pay.
* **Enable BLIK and put it at the top** — it's the most popular method in Poland; the order of channels and providers affects what the customer sees first.
* **Think about who pays the fee** — for more expensive methods (e.g. SMS), consider adding the fee to the buyer's price.
* **Keep your keys secret** — never send your API keys or the notification address to anyone.
* **Make a test purchase** — before announcing your shop, buy something yourself and check that the payment goes through and the item reaches the game.