Paying with a foreign Mastercard EU card

There are four ways to top up a zukko.pro balance: SBP, a bank card through PayPear, crypto, and — since September 16, 2026 — a foreign Mastercard card processed through a separate gateway called Fride. Here is how it works and what to do when a payment fails.

Why foreign cards need a separate processor

PayPear accepts cards issued by Russian banks and routes through the national payment card system (NSPK). A card issued by a bank in the EU never touches that route — it simply is not enrolled in NSPK. That is why a separate gateway, Fride, handles international Mastercard directly, without going through NSPK at all.

Because of this split, the /app/payments page in your dashboard shows two separate payment options rather than one generic "card" button: a regular card (PayPear, for Russian banks) and "Foreign Mastercard EU card" (Fride). It is easy to pick the wrong one, since the two differ only in the button label, not in placement.

How to top up

1. Open /app/payments in your dashboard.
2. Choose "Foreign Mastercard EU card."
3. Enter the top-up amount in dollars — between $2 and $594 for this method. Keep in mind that this method carries a commission of about 13%. Conversion to euros happens at Fride's exchange rate at the moment the card is charged.
4. Enter the card number, expiry date, and CVC on Fride's own form — this is a separate processor page, not a zukko.pro form, and card details should only ever be entered there.
5. Confirm the payment through 3-D Secure — usually a push notification in your banking app or a one-time SMS code.
6. Once confirmed, the balance updates in the dashboard and becomes visible through GET /v1/balance.

Common decline reasons

The bank blocks the first transaction to a new recipient. Many European banks are cautious by default about a first payment to an unfamiliar merchant and silently decline it. The first thing to check after a decline is your banking app — there is often a push notification asking you to manually approve or reject the operation.

The card is restricted to domestic payments only. Some debit cards ship with cross-border online payments disabled by default. In that case Fride gets rejected before the 3-D Secure screen even appears. Lifting the restriction is done in the banking app or by calling your bank's support line.

Exchange rate differences. The charge goes through in euros at Fride's rate at the time of the transaction, which can differ from the central bank rate or the rate Google shows by 1-3%. This is not a duplicate charge or a bug — it is how any conversion into a currency other than the card's billing currency works. Separately from the rate, this method carries a commission of about 13% — factor it in when comparing your statement with the top-up amount.

The amount is out of range. Mastercard EU top-ups accept between $2 and $594 per payment — a smaller or larger amount can't be topped up this way.

The card is not a Mastercard. This method only works with Mastercard-branded cards. A Visa from the same European bank will not go through here — use crypto instead, or SBP if you have a Russian bank account.

If you were charged but the balance did not update

First check the balance directly through the API rather than trusting a cached dashboard page:

curl https://api.zukko.pro/v1/balance \
  -H "Authorization: Bearer fetch_your_key"

The response contains the current account balance. If the balance has not moved but your banking app already shows the charge, do not initiate a second payment — confirmation from the bank can reach Fride with a delay of a few minutes because of how the 3-D Secure protocol itself works. If the balance is still unchanged after 15-20 minutes, contact support at https://t.me/zukkopro?direct↗ with the transaction time and the last four digits of the card.

Idempotency and automated top-ups

Idempotency-Key doesn't apply to top-ups: it only works for model requests (POST /v1/chat/completions, /v1/messages, /v1/responses). A Mastercard EU top-up goes through Fride's form with 3-D Secure confirmation, so protecting against duplicates is simple: if a payment doesn't show up right away, don't create a second one — wait and check the balance via GET /v1/balance. A script that watches the balance can notify you when it drops below a threshold, but the top-up itself is best confirmed by hand.

Card data security

The form that collects the card number, expiry date, and CVC belongs to Fride, not to zukko.pro — the gateway never sees or stores that data, only the authorization result reaches it. If anything outside the /app/payments page asks you to enter a card number to "top up your zukko.pro balance," it has nothing to do with the service.

If Mastercard EU does not work for you

If a card keeps getting declined and SBP is unavailable because the account is not with a Russian bank, crypto is the remaining option — it depends on neither NSPK nor bank card processing and works regardless of the card's or bank's country. Crypto is listed on the same /app/payments page next to the other payment methods.

How to be sure a top-up actually belongs on Fride

If you are unsure which of the two options on /app/payments applies to your card, the simplest check is not your country of residence but which bank physically issued the card. A Russian bank means PayPear, no matter where you currently are. An EU bank means Fride, even if you hold citizenship elsewhere. Confusion usually comes up for people who relocated and hold cards from both kinds of banks at once — in that case it is worth a single small test top-up to confirm which method actually works for the card you want to use, instead of guessing every time.

What shows up in the history after a successful payment

Once the balance updates, the new amount is visible in the dashboard and through GET /v1/balance. Top-ups don't appear in GET /v1/usage — that endpoint only lists model call spend (fields created_at, model, tokens, cost_cents). If there are several top-ups in a month and you want them in one table with your spend, take the top-ups from the dashboard and your bank statement, and the spend from /v1/usage.