Module · Payments
Payment providers
ExpertPress Payments connects to outside services in three roles:
- payment methods, which take the client's money (and give it back on a refund);
- payout methods, which send the specialist's share;
- cash registers, which issue the payment and refund receipts.
Each role has a built-in test option that runs inside WordPress and moves no money. Real providers are chosen on ExpertPress → Money → Settings (see Settings); their secret keys live only in wp-config.php.
The module makes no calls to outside services until you turn a provider on and add its keys.
Overview
| Provider | Role | Test mode | Live mode | Currencies | Holds and saved cards | Partial refunds | Bank split |
|---|---|---|---|---|---|---|---|
| Test bank (Тестовий банк) | payment | yes | no | any | yes | yes | yes |
| Monobank (Монобанк) | payment | yes | yes | UAH only | no | yes | test mode only |
| Stripe (test mode) (Stripe (тестовий режим)) | payment | yes | no | the Stripe account's settlement currencies | yes | yes | no |
| Virtual bank (test) (Віртуальний банк (тест)) | payout | yes | no | any | — | — | — |
| Manual: bank transfer and payment order number (Вручну: переказ у банку й номер платіжки) | payout | yes | yes | any | — | — | — |
| Stripe transfer (test mode) (Переказ Stripe (тестовий режим)) | payout | yes | no | must match the Stripe route | — | — | — |
| Test cash register (Тестова каса) | receipts | yes | no | any | — | — | — |
| Checkbox | receipts | yes | yes | — | — | — | — |
On Money → Settings, every payment method has a status line: "Ready." or "Not ready: …" with the reason (for example "no keys for the current mode", "does not accept USD", "not allowed in live mode"), followed by its limits and its Webhook URL.
Secret constants
Add these to wp-config.php above the line /* That's all, stop editing! */. Values are never shown on the admin screens. Administrators see a Constants table on Money → Settings that says for each monobank and Checkbox constant whether it is "set" or "none — this payment or cash register is off"; the Stripe constants are not listed there.
| Constant | Needed for |
|---|---|
EXPERTPRESS_MONOBANK_TOKEN_TEST |
monobank in test mode |
EXPERTPRESS_MONOBANK_TOKEN_LIVE |
monobank in live mode |
EXPERTPRESS_STRIPE_SECRET_KEY_TEST |
Stripe (must start with sk_test_ or rk_test_; live keys are ignored) |
EXPERTPRESS_STRIPE_WEBHOOK_SECRET_TEST |
Stripe payment events (starts with whsec_) |
EXPERTPRESS_STRIPE_CONNECT_WEBHOOK_SECRET_TEST |
Stripe connected-account events, used for Stripe payouts (starts with whsec_) |
EXPERTPRESS_CHECKBOX_CASHIER_PASSWORD |
the platform's Checkbox cash register, test mode |
EXPERTPRESS_CHECKBOX_LICENSE_KEY |
the platform's Checkbox cash register, test mode |
EXPERTPRESS_CHECKBOX_CASHIER_PASSWORD_LIVE |
the platform's Checkbox cash register, live mode |
EXPERTPRESS_CHECKBOX_LICENSE_KEY_LIVE |
the platform's Checkbox cash register, live mode |
EXPERTPRESS_FISCAL_STORAGE_KEY |
a long random secret used to encrypt each specialist's own cash-register keys, and payout account numbers other than IBAN. Without it, those are not saved. Do not change it once data is stored. |
Example:
define( 'EXPERTPRESS_MONOBANK_TOKEN_TEST', 'your-test-token' );
define( 'EXPERTPRESS_FISCAL_STORAGE_KEY', 'a-long-random-string' );
Test bank
The default payment method. It needs no account and no keys, and works only in test mode ("The test bank is available only in test mode. Live mode is not saved with it.").
When a client pays, they go to a test payment page on your own site instead of a bank. The page shows "Test bank — no money is taken", the invoice details and buttons for each outcome: Payment successful, The bank declined, The client closed the page, and under Other test outcomes (to check errors) further cases such as a delayed success or a repeated notification. For holds there is Hold and Capture the hold. Only the client of that booking or an administrator can open the page.
The test bank supports everything the engine can do (holds, saved cards, partial refunds, bank split), so you can try every flow before choosing a real provider.
Virtual bank (test)
The default payout method. Pay out on the Payouts tab immediately records the transfer as sent. Test mode only: when you save live mode, payouts switch to the manual method ("In live mode the virtual bank does not pay out: payouts have been switched to the manual path.").
Test cash register
The default cash register. It produces a Test receipt page marked "Not fiscal": "This is a copy of the body that would have been sent to the cash register. No fiscal receipt was created." Test mode only: live mode is not saved with it.
monobank
monobank internet acquiring takes card payments in UAH only. The client enters card details on monobank's page, not on your site.
What you need: a monobank merchant account and its API token (test and/or live).
Setup:
- Add
EXPERTPRESS_MONOBANK_TOKEN_TEST(and laterEXPERTPRESS_MONOBANK_TOKEN_LIVE) towp-config.php. - Make sure the shop currency is UAH (Money → Settings → Shop currency, or Settings → General → Pricing currency in the core).
- On Money → Settings, set Payment method: Monobank to On and save. The row must say "Ready."
The webhook address is sent to monobank with each invoice, so there is nothing to register in monobank's cabinet. The Webhook URL hint on the settings screen shows it for reference (by default https://your-site/wp-json/expertpress/v1/payments/monobank/webhook).
What is sent to monobank: the amount, currency, order reference, the payment line (see Booking payment line (client) in Settings), return and webhook addresses and, with the bank split, the receiver id and split amounts. The module later reads the payment status and requests refunds.
Limits:
- Partial refunds are supported.
- Card holds are not available ("A hold is built into the port and stays off until there is a decision on when the client pays.").
- Bank split works in test mode only. With a live token: "Split payments with a live token are off until the bank confirms." For the split, each specialist needs a monobank receiver id saved in their profile.
- Monobank saved-card wallet: the switch exists, but card saving and charging a saved card through monobank are not connected in this version; payments that need a saved card are refused with "Monobank card saving is not configured."
Stripe
Stripe is available in test mode only in this version ("Test mode only. Seller shares are paid later as Stripe transfers."). Use it to try card payments, card holds and Stripe Connect payouts. Live Stripe keys are ignored, and live mode cannot be saved while Stripe is on.
The client enters card details on Stripe's hosted page. Stripe Checkout Sessions and PaymentIntents are created by the module; card holds use manual capture; saved cards are stored on a Stripe Customer.
What you need: a Stripe account, its test secret key (or a restricted test key), and two webhook destinations.
Setup:
- In Stripe (test mode), copy the secret key into
EXPERTPRESS_STRIPE_SECRET_KEY_TEST. - On Money → Settings, set Payment method: Stripe (test mode) to On and save. Copy the Webhook URL from its hint (by default
https://your-site/wp-json/expertpress/v1/payments/stripe/webhook). - In Stripe, add a webhook destination for your account's events at that URL. The module acts on Checkout Session, PaymentIntent, SetupIntent, refund (
charge.refunded) and transfer events. Put its signing secret intoEXPERTPRESS_STRIPE_WEBHOOK_SECRET_TEST. - For Stripe payouts, add a second destination at the same URL for connected accounts' events (
account.updated). Put its signing secret intoEXPERTPRESS_STRIPE_CONNECT_WEBHOOK_SECRET_TEST.
What is sent to Stripe: the amount, currency, order reference, the product or service name, success and cancel addresses, an optional Stripe Customer id, and the order reference as metadata.
Stripe payouts
To pay specialists through Stripe, choose Stripe transfer (test mode) under Specialist payout method. This is refused unless:
- Stripe is on as a payment method ("Stripe payouts were not saved: they need Stripe as the payment provider. The virtual bank stays on."), because transfers are paid from the platform's Stripe balance, which only Stripe payments fill;
- the Payout route is "Ready".
The Payout route panel on Money → Settings shows the Stripe account country, the Proved settlement currencies, the Shop currency and the Result ("Ready", "Not supported" or "Unknown"). If it is not ready, it advises: "Change the shop currency to the Stripe account's settlement currency, or turn on settlement in this currency in the Stripe settings — then press “Check now”." Check now reads the route again.
Each specialist must complete Stripe verification on their Finances page (Verification with the payment provider → Start verification, later Continue verification). Until Stripe reports the account as ready, payouts to that specialist are refused ("The specialist cannot receive Stripe transfers yet."). If Stripe cannot pay out to the specialist's country, they see "Payouts through Stripe to your country are not available."
Manual payouts
Manual: bank transfer and payment order number has no bank connection. The accountant prepares the payout on the site, makes the transfer in the bank, then clicks Mark as paid out and enters the payment order number and transfer date. It works in test and live mode. See Refunds and payouts.
Checkbox
Checkbox issues fiscal receipts. No client contact data is sent; the module sends the goods or service name, amount and payment type.
Setup for the platform's own cash register:
- Set Checkbox fiscal service to On and save. Checkbox then appears under Cash register.
- Choose Cash register: Checkbox.
- Fill Platform cashier login (test) and/or Platform cashier login (live) and Product tax code in the platform's cash register.
- Add the matching
EXPERTPRESS_CHECKBOX_CASHIER_PASSWORD…andEXPERTPRESS_CHECKBOX_LICENSE_KEY…constants.
Specialist's own cash register: when Who issues the receipt is "Specialist, own cash register" (or the money scheme is the bank split), each specialist's receipts come from their own Checkbox cash register. The specialist's cashier login, tax code and keys are stored per specialist; the keys are encrypted with EXPERTPRESS_FISCAL_STORAGE_KEY. Until a specialist's cash register is set up, live payments for their bookings are blocked, and in test mode the client may see "Receipt issuing for this specialist is not connected yet."
Going live
Live mode means real charges. The Mode select on Money → Settings accepts Live only when every condition below holds; otherwise the save keeps test mode, saves the other fields and lists what is missing under Live mode will not be saved:.
- Every enabled payment method allows live mode. In this version that is only Monobank: turn the test bank and Stripe off.
EXPERTPRESS_MONOBANK_TOKEN_LIVEis set.- The cash register is not the test one:
- for the platform's cash register: Checkbox, a Platform cashier login (live), and both live Checkbox constants;
- for specialists' own cash registers:
EXPERTPRESS_FISCAL_STORAGE_KEY, plus each specialist's cash register (checked per booking at payment time).
- The payout method allows live mode. The virtual bank and Stripe transfers do not; the save switches payouts to the manual method automatically.
When live mode is on, the settings screen shows "Live mode is on. Real charges are possible only when the live token constant is set."
Each payment keeps the mode it was created in. Switching the mode does not change payments that are already open.