↑↓ selectEnter openEsc close

    1. Elbuz

    How to accept monobank payments in your store

    6 min readUpdated

    monobank acquiring (Plata by mono) takes payment right after checkout. The customer pays on the monobank page with any bank's card, Apple Pay or Google Pay, and the order becomes paid automatically. Just enter your monobank token in the Elbuz store settings.

    When you need this:

    • Your business banks with monobank — site payments go there, the status updates itself.
    • Stock has to be checked first — a hold blocks the money, charged when you confirm.
    • The monobank receipt needs the order contents — products, shipping and discounts are sent.

    Where to start: “Store settings” → “Checkout & payment” → monobank → token and “Enabled”.

    What monobank payments can do

    How to connect monobank acquiring

    You need a sole proprietor or company account at monobank with online acquiring connected. The bank tells you the terms and the fee.

    1. Get the token. In your web.monobank.ua account, open Internet acquiring → keys and copy the token (X-Token). It's secret — never send it to anyone.
    2. Open the module screen. “Store settings” → the “Checkout & payment” section → the monobank card.
    3. Paste the token into the “Token (X-Token)” field of the “Connection” block.
    4. Turn on the “Enabled” switch at the top of the screen.
    5. Click “Save”. The settings go to the store right away, and “Saved and applied in the store” appears at the bottom.
    The Checkout & payment section of Store settings with the monobank payments module in the list
    1monobank payments module
    2Module status mark
    1. monobank payments — opens the monobank payment setup screen.
    2. Status mark and switch — show whether shoppers see this payment method and whether the latest changes have reached the store.
    The monobank payments screen, Connection block
    1Enabled switch
    2Token (X-Token)
    3Webhook URL
    4Still to set up
    5Status pill
    1. Shows monobank to customers after saving.
    2. The token from the monobank cabinet; after saving only a mark that it is set is shown.
    3. The address for bank notifications; the module sends it itself, nothing to enter.
    4. What is still missing for payments to work.
    5. The module state in the store.

    An enabled module won't save without a token: the field shows “Required — the module will not work without it”. The screen won't accept a token shorter than 20 characters or one with spaces. The token isn't shown after saving — to change it, click “Replace” and paste a new one.

    You don't need to enter anything in your monobank account: the module sends the address for payment notifications with every invoice itself. It's shown in the “Connection” block as “Webhook URL”, in case the bank asks for it.

    What else isn't set up appears on the right, in the “Still to set up” card. How the window works in general is covered in “Store settings”.

    What the customer sees and for which orders

    In the list of payment methods, the customer sees “Card payment via monobank” with a hint about Visa, Mastercard, Apple Pay and Google Pay. After confirming the order — a short “Opening the monobank payment page…” and then the bank's page itself.

    • Paid — they return to the order success page.
    • Didn't pay — they return to checkout with “The payment was not completed. Try again or choose another payment method.” and the reason from the bank. The cart and details are kept.
    • The bank page didn't open — “Could not open the payment page…” and a “Pay” button to try again.

    The payment invoice is valid for 24 hours. A retry within that day opens the same invoice if the order total hasn't changed.

    Fields of the “Payment” block

    The Payment block of the monobank screen
    1Charge mode
    2Invoice currency
    3Send the cart contents
    4Product code in the receipt
    1. Charge the money at once or block it until you confirm.
    2. The currency the order total is converted into.
    3. Products, shipping and discounts on the payment page and in the receipt.
    4. Which product field goes into the receipt as the code.
    FieldWhat it doesDefault
    Charge mode“Charge immediately” or “Hold the funds, charge later” (hold)Charge immediately
    Invoice currencyUAH, USD or EUR. The order total is converted into it at the store rate. USD and EUR only if the bank enabled them for youUAH
    Send the cart contentsThe order contents on the payment page and in the monobank receipt — what exactly is senton
    Product code in the receiptOnly with the cart contents: model, SKU, product ID in the store, UPC or EAN barcode, ISBN or manufacturer part numberModel
    Receipt to the buyer emailmonobank emails the receipt to the address from the orderoff

    The store takes the invoice currency from its own currencies. If the store doesn't have it, customers won't see monobank. Currencies and rates reach the store from the “Currencies” window in Elbuz if the currency row has “Activity” and “Export to website” on: Exchange rates.

    Order contents in the receipt

    Products go at their price with tax, along with photos. Shipping and other surcharges are separate lines, and discounts are spread over the products. If a product's code field is empty, its product ID is sent instead.

    If the discount is larger than can be spread over the products, the invoice goes without contents — as a total only. monobank issues the fiscal receipt with the contents if you've connected fiscalisation at the bank.

    For which orders to show it

    • “Geo zone” in the “Where to show” block — the payment is shown only to customers with a shipping address in this zone; “All zones” — to everyone.
    • “Sort order” — the position in the payment list; a smaller number goes higher.
    • “Payment purpose” in the collapsed “Additional” block — the text in the payment. %s is replaced with the order number. Empty — “Payment for order #” and the number.
    • “Bank request log” in the same block — records requests to monobank and the bank's answers for support. Off by default; the token never goes into the log.

    Elbuz support sets a custom name, description and minimum cart total for the method. Below the minimum, the customer sees the method as inactive: “Payment "…" available from …”.

    Hold and order statuses

    Charge right away or block the money

    This is the “Charge mode” field in the “Payment” block.

    Charge modeWhat happens to the moneyWho it suits
    Charge immediatelyCharged immediatelyGoods in stock, shipped right away
    Hold the funds, charge laterBlocked on the card; charged when you confirm the holdThe supplier ships the goods, stock has to be checked

    With a hold, the “Order statuses” block shows the “Funds on hold” field. If it's the same as “Paid”, the right side shows “The “Paid” and “Funds on hold” statuses are the same, so a hold cannot be told apart from a payment”.

    A hold lasts a limited time: after that the bank lifts the block itself and the money goes back to the customer. The exact period is in the monobank terms. Confirm the hold as soon as you have the goods.

    Which statuses are set

    The store sets the status itself when monobank reports a payment. You choose which ones in the “Order statuses” block, from the store statuses.

    The Order statuses block with four status fields
    1Paid
    2Funds on hold
    3Refunded
    4Status if the payment total does not match
    1. Set when the customer paid or you confirmed the hold.
    2. Money is blocked and waiting for confirmation; the field is shown only for a hold.
    3. Money returned in full or the hold cancelled.
    4. Paid, but the order total has changed: the order gets this status so you can check it.
    FieldWhen it is setDefault
    PaidThe customer paid, or you confirmed the holdProcessing
    Funds on holdThe money is blocked and waits for your confirmationProcessed
    RefundedThe money was refunded in full, or the hold was canceledRefunded
    Status if the payment total does not matchThe customer paid the invoice, but the order total changed in the meantimePending

    When a payment or hold gives the order its first status, the customer gets the usual order email. A captured or released hold and a full refund also change the status — the customer gets a status change email. A partial refund doesn't change the status, and no email is sent.

    Until monobank confirms the payment, the order stays unconfirmed and doesn't count as new. If the customer didn't pay, the order isn't canceled: they can pay for it again.

    The store verifies bank notifications: it takes the status and amount from monobank, not from the notification itself.

    The payment amount doesn't match the order total

    This happens when the customer changed the cart after a payment attempt, or the rate changed between the invoice and the payment. The money is received, so the order is confirmed and arrives in Elbuz, but not as paid. It gets the status from the “Status if the payment total does not match” field.

    This status must differ from “Paid” and “Funds on hold”. If it matches, the store sets the new-order status, and if that one equals “Paid” too, the order stays unconfirmed. The right side flags such a match: “The amount-mismatch status equals “Paid” or the hold status…”.

    In stores set up earlier, “Funds on hold” may be “Pending” — the same as the mismatch status. Then the right side shows this warning: choose a different status for the hold or the mismatch.

    Refunds and holds in the order card

    A site order arrives in Elbuz as a “Customer order” document with the payment type “Bank card”. Its card has a “Payment in monobank” block. It shows the payment state, the amount, how much was captured and refunded, how much can still be refunded, and all payment attempts.

    Only the buttons available for the order right now are shown:

    ButtonWhat it doesStatus after
    RefundRefunds the whole amount or part of it: the amount field is already filled with the balance; for a partial refund, enter a smaller oneFull — “Refunded”, partial — no change
    Capture holdCharges the blocked amount, or a smaller one if some products are missing“Paid”
    Release holdCancels the block, and the money goes back to the customer“Refunded”
    Refresh statusGets the payment state from monobank if the notification didn't arrive. A repeat duplicates nothingper the payment state

    Before each money operation, the app asks for confirmation; for a refund and a hold release, with the warning “This operation cannot be undone.”. The order status on the site changes the same way as after a monobank notification.

    If the store didn't respond, a “Retry” button appears under the message: it repeats the same operation, and the money doesn't move a second time. Clicking the original button again starts a new operation.

    Only a user with the “Payment operations: refund, hold, credit” right can refund money and manage holds — by default, the owner. “Refresh status” is available to everyone who can see the order.

    Once there are orders through monobank, the module screen header shows the last 30 days: count, total, average order value and the share of canceled or refunded ones.

    How to check with a test payment

    1. Get a test token at api.monobank.ua — you sign in with the monobank app. Enter it in “Token (X-Token)” and save.
    2. Place an order on the site for yourself, choose “Card payment via monobank” and pay. With a test token, no money is charged.
    3. Check that the bank page shows the right amount and that the order arrived in Elbuz under “Customer order” with the payment type “Bank card”.
    4. Replace the token with the live one from your web.monobank.ua account and save.

    Scenarios

    Electronics to order: charge after checking stock

    “Charge mode” — “Hold the funds, charge later”. In “Funds on hold”, choose a status other than “Paid”.

    The item is in stock — “Capture hold” in the order card. Some of it is missing — enter a smaller amount. Nothing is available — “Release hold”, and the money is unblocked.

    A monobank fiscal receipt with the order contents

    Turn on “Send the cart contents”, and in “Product code in the receipt” choose a field that every product has filled in, for example SKU. The customer sees the product list on the payment page, and the same lines in the receipt.

    Prices in dollars, payment in hryvnias

    “Invoice currency” — UAH. The store converts the total at the rate that came from the Elbuz “Currencies” window. If the rate in Elbuz is updated, the invoice amount changes after the next export.

    If the rate changed between creating the invoice and the payment, the order arrives with the amount-mismatch status: how it works.

    What to do when payments don't work

    What you seeWhyWhat to do
    The customer doesn't see monobank at checkout The module is off, the token isn't set, the invoice currency isn't in the store, the address isn't in the geo zone, or the method is restricted in the checkout settings Check “Enabled”, the token, “Invoice currency” and “Geo zone”. The currency — in the “Currencies” window with “Activity” and “Export to website”. All correct — Elbuz support will check the checkout
    The customer sees “Could not open the payment page” Most often a wrong token, or acquiring isn't activated yet Paste the token again with “Replace”. Didn't help — turn on “Bank request log” in the “Additional” block, repeat the payment and write to Elbuz support
    The payment went through, but the status didn't change The bank notification didn't reach the store Click “Refresh status” in the order card. The status also updates when the customer returns to the store from the bank page
    A paid order arrived in Elbuz with the amount-mismatch status, not “Paid” The customer changed the cart after a payment attempt, or the rate changed Compare the payment in your monobank account with the order total and decide: extra payment, refund or order change
    The amount on the bank page differs from the price on the site The order is in another currency, and the total is converted into the invoice currency Check the rate in the Elbuz “Currencies” window and export it to the store

    FAQ

    Is this the same as monobank “Purchase in Installments”?

    No. “Purchase in Installments” is a separate payment method in the credits module, with its own settings (Credit and installment payments). This module takes full payment or a hold.

    What happens if I turn the module off?

    monobank disappears from checkout. The token and settings are kept: turn it back on and everything is in place. Payments started before you turned it off are confirmed only when the customer returns from monobank to the store.

    Can I send the customer a monobank payment link?

    Yes, from the order card in Elbuz. The token for links is set separately: Payment links.

    Does the customer get an email after a refund?

    Yes, for a full refund: the status changes to the one chosen in the “Refunded” field, and the customer gets the usual status change email. For a partial refund, the status doesn't change and no email is sent.

    The customer closed the bank page without paying — where is the order?

    It stays unconfirmed and doesn't arrive in Elbuz. The invoice is valid for 24 hours: the customer can go back to the cart and pay again.

    The zone I need isn't in the “Geo zone” list — what do I do?

    Elbuz support creates the zone, for example “Ukraine”. Then choose it in the “Where to show” block.

    Where to find it and who has access

    Menu
    Directories → Operations → Store settings → “Checkout & payment” → the monobank card
    Access rights
    the “Store settings” window in group permissions; refunds and holds — the “Payment operations: refund, hold, credit” right
    Prepare
    a sole proprietor or company account at monobank with online acquiring, the token (X-Token)

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free