Manual Payment
Провайдер по умолчанию для ручного приёма оплаты
Manual payment provider for Medusa
A payment provider for Medusa 2 for payments you collect outside Medusa, such as bank transfer, cash on delivery or invoice. It does not contact a payment gateway: the payment session is authorized as soon as the customer places the order, and you capture or refund the payment from the Medusa admin once the money arrives.
Registering it next to Medusa's built-in gives the payment its own provider id, so your storefront and admin can tell these payments apart from other providers.
Version 2 adds settings you manage in the Medusa admin, per provider: availability rules, a payment fee, payment instructions, bank accounts, payment references, QR codes (EPC and UPN), automatic capture and automatic cancellation of unpaid orders. Everything is off by default. A provider you have not configured behaves like 1.x: it is available everywhere, you capture payments by hand, and it adds no fee, instructions, bank accounts, references or QR codes.
Compatibility
| Plugin version | Medusa version | Node.js |
|---|---|---|
| 2.x | 2.22.x | 22.22+ |
| 1.1.x | 2.19 to 2.21 | |
| 1.0.x | older than 2.19 |
2.x declares as a peer dependency. Using an older Medusa version? Install the matching plugin version, for example v1.0.3:
Installation
Or with yarn:
Configuration
Add the package to (it provides the admin page, the API routes, the jobs and the database module) and register the provider with the Payment Module, using the subpath:
Then run the migrations, which create the plugin's tables:
npx medusa db:migrateThe provider's only option is (see below). Any other option makes Medusa fail at boot; configure the provider in the admin instead.
Medusa stores the provider as . With the configuration above, its id is . To offer several manual methods, such as bank transfer and cash on delivery, register the provider once per method with a different (for example → ). Each one has its own settings.
Provider type
Declare what kind of payment a provider is with the option, so your storefront and admin do not have to guess it from the provider id:
| Meaning | |
|---|---|
| The customer pays by bank transfer. | |
| The customer pays the courier or at pick-up. | |
| The customer pays an invoice later. | |
| Anything else. This is the default when is missing. |
An invalid makes Medusa fail at boot. Where shows up:
- Payment data: every provider method returns as its , so Medusa stores it in the payment session and the payment () and keeps it through authorize, capture, refund and cancel. A payment keeps the type it was created with if you change the option later.
- Store API: each provider in has a , and returns (from the payment data, else from the configuration).
- Admin API: (sorted by rank, see Order) and return the . Saved settings also carry their row (), which stays the same across saves and is what translations reference.
- TypeScript: the package exports , and the type guard .
- Backend code: returns an order's payment instructions exactly as the store order endpoint does, for emails and documents: translated for the order's locale, else . It creates the order's snapshot if needed. returns each provider's label by provider id (translated for , when none is set), one entry per provider with saved settings, for staff notifications, invoices and admin lists. returns the registered manual providers as , sorted by rank (see Order), for picking a provider in your own code: is the plugin's Enabled setting ( while the provider has no saved settings).
The admin page adapts to the type. It shows the type in the provider list and on the provider page, and for it hides the Bank Accounts section and the reference and QR code settings, which do not apply. Settings you saved earlier stay as stored. , and show everything. The store order endpoint follows the same rule: for it returns no bank accounts, and .
Usage
-
In the Medusa admin, go to Settings → Regions, edit a region and add to its payment providers.
-
In your storefront, create the payment session with . With the JS SDK:
-
When the payment arrives, capture it from the order page in the admin (or let the plugin capture it, see below). Refunds are recorded the same way.
Admin settings
Go to Settings → Manual Payments in the admin. It lists every registered provider whose id starts with , with its type, status, capture mode, countries and fee. Click a provider to open its page, which shows these sections; edit one with Edit in its menu (bank accounts are added, edited, reordered and deleted one at a time):
- Provider (header card): the Label, a display name for the provider (up to 100 characters; blank uses the name derived from the provider id, for example "Bank Transfer"), the Description, a short line shown under the payment method at checkout (up to 500 characters), and Enabled. The label is the provider's name in the admin (list, breadcrumb and header) and in the store API (see Eligibility), which also returns the description.
- Availability Rules: countries (matched against the cart's shipping address), currencies (matched against the cart's currency) and shipping options (matched against the shipping method chosen in the cart), each with all, only selected, or all except selected; and the fee label. Amounts in the section's menu opens Medusa's price grid, like Edit Prices, with a row each for the minimum cart total, maximum cart total and payment fee and a column for each currency the saved currencies rule allows (blank means no limit or no fee; saving drops amounts for currencies the rule excludes, and so does saving a rule that excludes them). Amounts are in major units, for example . The minimum and maximum totals exclude the plugin's own fee.
- Payment Details: the instructions shown to the customer, a reference template ( is the order number), the reference scheme (none, , or ), the QR code type (none, EPC or UPN) and the UPN purpose code.
- Bank Accounts: one or more accounts (recipient, the recipient's address, postal code, city and country, IBAN, BIC and bank name). An account can be limited to shipping countries; an account with no countries is the default one.
- Capture And Auto-Cancel: the capture mode and automatic cancellation of unpaid orders.
Every setting is optional and applies only once you set it.
Order
Each provider has a , its position in the list ( first; a provider without saved settings counts as , and equal ranks are ordered by provider id). Reorder the providers with Move Up and Move Down in a row's menu on Settings → Manual Payments. The order is the checkout order: the eligibility endpoint, and return the providers sorted by it, so a storefront or backend code that picks a provider automatically can take the first match.
with sets the order through the API: the body must list every registered manual provider exactly once (else ), each provider's rank becomes its index, and the response is the sorted list, like .
Translations
The label, the description, the fee label and the instructions are translated with Medusa's own translations, like product titles. This needs Medusa's feature flag (, or in ) and the store's locales, which you add under Settings → Translations.
- Save the provider's settings once. Until then the provider has no settings to translate, and Translate is disabled with a hint.
- Choose Translate in the menu of the provider's header card, or of the Availability Rules or Payment Details section. It opens Medusa's translation editor for the provider's settings (), where you enter the label, description, fee label and instructions per locale. The text you enter in the plugin's settings is the default, used for locales without a translation and when the flag is off.
The plugin uses the translation whose locale matches exactly, like Medusa ( doesn't use an translation). A blank translation falls back to the default.
- Fee title: the fee line item is titled in the cart's locale, or the request's locale (Medusa's parameter or header) when the cart has none. Medusa translates only items with a variant, so the plugin re-titles the fee itself when the cart's locale changes (on ). Like Medusa, it doesn't re-title when the locale is removed. An order keeps the fee title it had when the cart was completed.
- Label: the eligibility endpoint returns it in the cart's locale (else the request's), and the store order endpoint and in the order's locale (else the request's), like the instructions.
- Description: the eligibility endpoint returns it in the cart's locale (else the request's).
- Instructions: the store order endpoint and return them in the order's locale (copied from the cart), or the request's locale when the order has none.
Availability rules and the fee
When a payment session is created for an unavailable provider, or when the cart is completed after it became unavailable, the request fails with an error whose message is . The reason is one of , , , , or .
Completing the cart also checks that its fee items are what the paying provider charges now: its one fee at the configured amount, or none. They can differ when the fee setting changed after the session was created, or when a cart change made Medusa delete the session while the fee item stayed. The plugin then corrects the fee items and fails with . The corrected total makes Medusa drop the session, so the customer chooses the payment method again at the new total.
Countries, currencies and shipping options each take one of three modes: all (no restriction), only selected (the cart's value must be listed) or all except selected (the cart's value must not be listed). A cart without a shipping address fails both country modes. A cart without a shipping method yet fails "only selected shipping options" and passes "all except selected shipping options"; the check runs again when the cart is completed. "Only selected" needs at least one item; "all except" with none selected is the same as all.
Enabled is a plugin setting of each provider (⋯ → Edit on the provider's header card in the admin, on by default). Turn it off to stop offering the provider for new checkouts: it fails the checks above with , and the eligibility endpoint returns with . It doesn't affect existing orders, which are still captured, auto-cancelled and shown by the store order endpoint. Medusa's own enabled flag is not used, because the Payment Module resets it at every boot. Medusa's region assignment (which providers a region offers) still applies on top.
The fee is added to the cart as a line item when the payment session is created, and replaced or removed when the selected provider or the fee changes. It has no variant or product, its title is the fee label (default ) and its metadata has set to the provider id. Storefront and email code that assumes every line item has a variant or product must handle it, for example:
The fee is entered like your prices in that currency: tax-inclusive when the currency's prices include tax (the currency's price preference, as Medusa applies it to a plain per-currency price), net otherwise. With tax-inclusive prices in a currency a fee of costs the customer . The eligibility endpoint returns the amount as configured.
The fee item doesn't require shipping, but Medusa still counts it as an item to fulfil. So when the order is placed the plugin marks the fee fulfilled through the order module's , which sets its fulfilled quantity without creating a fulfillment. No fulfillment exists for the fee and nothing is sent to a fulfillment provider. The order's fulfillment status (not fulfilled, fulfilled, shipped, delivered) comes from the product fulfillments alone, and the admin's Unfulfilled Items lists only the products.
This runs on Medusa's event, under a lock per order, and never on canceled orders. A missed is caught up by the order's next . It fails, and logs the error, while the order has an active order change (for example a requested order edit); the next fulfillment then catches up. Only the fulfillment status is affected, never the payment.
The admin offers delivered items for returns and claims, so it doesn't offer the fee. A return of the fee is possible through Medusa's API only. Capture on delivery doesn't wait for the fee, because one delivered fulfillment is enough.
Capture and auto-cancel
The capture mode is one of:
- manual (default): you capture from the admin.
- on order: the payment is captured when the order is placed.
- on delivery: the payment is captured once the order has a delivered fulfillment.
Capture on delivery happens right away: when a fulfillment is marked as delivered (Medusa's event), the plugin captures that order's payments through Medusa's . A job runs every minute and captures what matches (this is how on order is captured, and the fallback for a missed delivery event). Both use the same rules. They never capture a payment twice: each capture runs under a lock per order and is checked again inside it, and payments that already have a capture or a refund, canceled payments, and draft, canceled and archived orders are skipped. If you run several Medusa instances, use a shared locking provider (for example the Redis locking provider) so the lock works across them.
Auto-cancel cancels unpaid orders after a number of days. A job runs hourly and cancels through Medusa's . It only cancels and orders, and it never touches an order that has a fulfillment that isn't canceled, or a capture on any of its payments.
Both settings apply to existing orders on purpose: turning on capture mode or auto-cancel, or shortening the auto-cancel days, affects open orders as well as new ones. Before you save such a change, the admin shows how many orders will be captured or cancelled and asks you to confirm.
Storefront endpoints
Both store endpoints need the usual publishable API key header.
Eligibility
returns one entry for each enabled manual provider in the cart's region, sorted by rank (see Order), so the storefront can show them in that order and hide or explain unavailable methods before the customer picks one:
is only present when is . is the provider's label from the admin, translated for the cart's locale (else the request's, see Translations), or when none is set: fall back to your own name for the provider then (for example from ). is the short line to show under the payment method, translated like , or when none is set. is when the provider has no fee in the cart currency. is the title the fee item gets, translated for the cart's locale (else the request's, see Translations).
Order payment instructions
returns what to show the customer after the order is placed. is when the order has no manual payment or the provider has no settings. is the provider's label translated for the order's locale, or when none is set (fall back to your own name).
- is translated for the order's locale, or the request's locale (Medusa's query parameter or header) when the order has none, and falls back to the default text (see Translations). It is when there are no instructions.
- is generated once per order from the template and scheme when the order is placed, and stays the same afterwards, even when the template or scheme changes.
- holds the accounts for the order's shipping country, or the default account. They always reflect the current settings, so accounts you edit, add, delete or reorder later show on existing orders too.
- Each account's , , and (ISO 3166-1 alpha-2, lowercase) are the recipient's address, with Medusa's address field names; each is when not set.
- is the payload text of the QR code, not an image. It is when is or the payload can't be built (QR codes need EUR and a complete account).
Example storefront code:
Rendering the QR code
Render the payload with a QR library. Both formats have fixed requirements:
| Type | Character set | Error correction | Other |
|---|---|---|---|
| EPC | UTF-8 | M | At most 331 bytes |
| UPN | ISO-8859-2, with ECI 000004 set | M | QR version 15, byte mode, at most 411 characters |
EPC (the European Payments Council "Girocode"), with the package:
UPN QR (Slovenia) must be encoded as ISO-8859-2 bytes, not UTF-8, so convert the payload first, for example with :
Which QR library can take raw bytes and an ECI header differs, so see your library's docs for ECI support.
QR payloads are only built for EUR. In the UPN payload the purpose text is the payment reference; with no reference it uses model ("no reference").
Migrating from 1.x
- Change the provider's to . Keep its .
- Add to .
- Remove any options you passed to the provider, except the new . Other options are rejected at boot; the settings are in the admin now.
- Run .
Provider ids () do not change, so existing orders, payments and region settings keep working. With no settings saved, the provider behaves as it did in 1.x.
Contributing
Bug reports and pull requests are welcome. Read the contributing guide and the code of conduct first. Report security vulnerabilities privately as described in the security policy.
License
MIT © Rok Mohar

