Skip to main content

Held payments on Medusa

For the Medusa store's developer and the staff who handle held payments. Each row on the admin's Held payments page says why it is there and which actions it allows now.

Checkout and wallet payments​

When a payment cannot be matched to an order safely (the cart changed during payment, the amount does not match, or the store could not create the order), the plugin does not complete the cart and does not refund on its own. It lists the payment on Held payments under Orders, where you can refund a checkout payment or mark it resolved.

Paid, order not created: the shopper paid, but Medusa did not create the order. Either the plugin's automatic retry failed or, from 1.6.0, Medusa's default locking module is not a shared one, so the plugin does not complete orders by itself (recovery). Check the cart and the payment in Von Payments, then complete the order with the shopper or refund it. Without a shared locking module, a held wallet payment or held card that has no order is listed as Payment held, no order instead (below).

Wallet payments have their own actions:

  • Payment held, no order: the shopper approved a payment that is only held (Apple Pay or Google Pay, or a held card) but no order was created. Nothing was taken. Release drops the hold. Complete the order creates the order: a wallet payment is then taken, and a held card is taken when the order is fulfilled or when you press Capture.
  • Payment held, release failed: the cart changed or was cancelled after the approval, and the hold could not be dropped automatically. Nothing was taken. Release it.
  • Not collected yet, retrying: taking the held wallet payment failed (usually a short outage). The plugin retries for 2 hours and lists it here within about 10 minutes. Nothing for you to do.
  • Wallet payment not collected: the retries ended without the payment. Open order to capture the payment or cancel the order. Don't ship that order until the payment is captured.

Cancelled, payment not closed (1.6.0 and later): the order was cancelled, but the plugin could not close its payment, so the shopper's card may still be held or charged. The row comes from Medusa's own records, so it shows even when the plugin's database connection is broken.

  • Release checks Von Payments first. It releases a held payment and never takes it, closes a checkout that could still take a card, and closes the payment in Medusa. If Von Payments already took the money, the row moves to a refund row.
  • Mark resolved also checks Von Payments first. It works only when Von Payments shows nothing held, taken or open to a card. It cannot be saved while the setup check's collection_handle line fails: use Release.
  • While the bank is still checking the payment, both ask you to try again in a few minutes. If money arrives after you closed the row, the payment comes back here with its Refund button.

Renewal and offer charges have their own actions too (below).

The charge must equal the cart's total (1.2.0 and later). Before Medusa places an order, the plugin checks the amount charged against the payment, its payment collection and the cart's total as Medusa computes it at that moment. Medusa itself does not compare them. If your own code changes a cart without Medusa updating its payment, the charge is held as Amount doesn't match, and no order is created at the old amount. When the cart total cannot be read, the charge is held as Couldn't confirm amount. Refund either one from Held payments, or settle it with the buyer and mark it resolved.

The checkout page makes the same check before Place order. When the total it shows is not the payment's, it reloads once. If they still differ, the shopper can pay, and the plugin holds that charge as above instead of creating an order.

Renewal and offer charges (1.2.1 and later)​

A renewal or one-click offer charge goes on Held payments when Von Payments cannot confirm it, or when the plugin finds a payment it cannot settle by itself. While the row is open, that renewal order takes no more renewal charges.

If Von Payments could not check the request, the plugin sends the identical request again every few minutes for up to 24 hours (an offer: until its offer window ends). This can never charge twice, and the row's actions stay closed meanwhile. After that the result is unknown, not failed, and a person decides. Each row shows only the actions it allows now, and says why. A few rows have none on purpose: a renewal record the plugin cannot read or tie to the order (the order stays blocked), an offer record it cannot read, and an offer payment it is still finishing.

On a renewal row:

ActionWhat it does
Check this orderReads Von Payments and Medusa, then acts on what it finds. It never charges anyone. It searches Von Payments for this renewal's payments, so your secret key must allow payment_intents.read (restricted keys).
Free without proofFrees the order, so the next renewal can charge the customer. Only for a renewal whose result is unknown, where Von Payments shows no payment and the renewal's record says its mode (test or live). It opens 30 minutes after the row's last change, but waiting proves nothing: a late charge can appear with no time limit, so check the Von Payments dashboard by order id first. Type the order id and tick I checked this order in the Vonpay dashboard. The plugin checks again first and records your name. Where the background job runs (recovery and saved cards on; the row says), it then searches once a day for 7 days and blocks the order again if a payment turns up. Elsewhere nothing searches again.
Close and keep blockedSends nothing to Von Payments and changes no money. No more renewal charges go out for that order. The row moves to Resolved, where Check this order can reopen it.

On these rows, refund in Von Payments when the row says so: Check this order then reads the refund and updates the row. Anywhere else, refund from the Medusa admin, because a refund made in Von Payments does not reach your store (Refunds).

What Check this order can report:

  • Paid and recorded: the renewal is paid, and the row leaves the list.
  • Renewal charged, order unpaid: a payment went through and Medusa has no record of it. It is recorded as charged, so no second charge can go out. The background job records it in Medusa; if the row says the job is not proven to run, wait for it or close the row. If the job stopped trying, refund it in full in Von Payments and check again, or close the row. Never mark the order paid by hand: the plugin reads that as paid twice.
  • No money left standing (failed, voided, or refunded in full): the order is freed, and later renewals go on.
  • Not finished: the row names the payment, and the plugin keeps reading it.
  • The customer may have paid twice: refund the extra Von Payments payment in full, then check either row. A payment Medusa recorded another way stays after any refund: settle it by hand and close the row.
  • Another renewal attempt on this order may also have charged the customer, result unknown: leave it held (the background job keeps reading both) or close it. Refund this payment only after you confirm in Von Payments that the other attempt was charged and you keep that one.
  • A wrong amount or customer: refund it in Von Payments.
  • Nothing found: nothing changes, and Free without proof is offered.

It changes nothing when something cannot be read, when a payment does not prove it belongs to this order, when a refund is still in progress, when more than one payment stands, or when the record of when the renewal was first sent is missing.

On an offer row, Close this offer is the only action. It changes no money: nothing is sent to Von Payments and nothing is refunded. For a charge whose result is unknown, it cancels the offered item's open order change, opens 30 minutes after the row's last change, and asks for the same typed order id and tick. A wrong close leaves a charged buyer with no item, no alert and no automatic refund, so check the Von Payments dashboard first. If the buyer was charged, refund it in Von Payments or add the item to the order yourself.

The background job proves it runs. The list hides an unrecorded paid renewal only while the job shows, in its own table, that it ran in the last 15 minutes and finished every paid renewal it found. Otherwise the row shows, with a banner that says why. The setup check's job_status line fails while that table cannot be read (Apply an update).

Renewal periods (1.4.0 and later)​

With subscription renewals from ReorderJS, the plugin keeps a record of each renewal period and charges it once. Each period row shows a description, not a title. Match its opening words to one of these cases:

CaseWhat it meansWhat to do
"This subscription period is already paid…"ReorderJS asked to charge a paid period again. The customer has paid. ReorderJS keeps making a new unpaid order every 5 minutes until that renewal is closed in ReorderJS.Cancel the extra unpaid orders in Medusa. Then press Keep blocked, or Reopen this period if the earlier payment was refunded and the customer must pay for the period again.
"An earlier renewal charge of this subscription period is still not finished…" or "The result of an earlier renewal charge of this subscription period is unknown…"A charge of the period has no result after an hour, or has not finished after 24 hours. The plugin never frees the period by itself.Find the charge in the Von Payments dashboard. If it must not go through, cancel it there, then press Check with Vonpay: the period is then free and the next renewal charges. A charge with no result offers only Check with Vonpay until it is 24 hours old. After that, once the dashboard shows no charge for the order, Reopen this period lets the next renewal charge.
"The renewal for this subscription period was declined…"The period's card declined and ReorderJS still makes new orders for it: from the first refused charge after a decline marked final, or eight days after any other decline.Ask the customer for a new card in ReorderJS, retry the declined order in ReorderJS (at least 24 hours after its last try, and not after a final decline), close the renewal in ReorderJS, or press Reopen for one order. Cancel the extra unpaid orders in Medusa. Keep blocked is offered here too.
ActionWhat it does
Keep blockedHides the row for 24 hours. If ReorderJS is still asking after that, the row comes back. Charges nothing.
Reopen this periodLets the next renewal of the period charge the customer again. It asks for the order id (or, when the row names no order, the Von Payments payment id) and the tick I checked Vonpay; a row that names neither offers no Reopen, so press Check with Vonpay first. The plugin then checks every payment of the period in Von Payments, back about a year: each must be refunded in full or have ended with no money, or nothing changes. Your name and the time are kept on the record.
Reopen for one orderAsks for the order id the row names, the tick, and a short reason (3 to 200 characters). Never type a card number there: a reason with 12 or more digits in a row is refused. The plugin then lets one charge of that order through, once, within 24 hours (ReorderJS's next retry of that order), and never for a period already paid. After a decline marked final, charging the same card again can bring card-network fees. Keep blocked, or a charge of another order of the period, cancels a reopen not used yet. Your name, the time and the reason are kept on the record.

A charge made by plugin 1.3.0 or older is not in the record, so the plugin cannot find it. Resolved period rows leave the list after 30 days.

Held cards (1.5.0 and later)​

With card hold, then capture on, the plugin lists a held card here when it needs you:

  • Card held 3+ days, capture or release soon: the money is not taken yet. Banks drop a hold after about 5 to 7 days, and the payment is then lost. Open the order, then Capture the payment or Cancel the order to release the hold.
  • Order fulfilled, held card not collected: the whole order is fulfilled, but the held card is not recorded as taken. The amount due may be more than the hold, or nothing may be due. The amount may not be readable, the order may have more than one held card, or a capture may have failed or not finished. While Retrying until shows, the plugin keeps trying. Open the order, then Capture the amount due (up to the held amount) or Cancel the order.
  • Held card not collected, plugin stopped trying: Von Payments refused the capture, recovery is off, or the hold is about 7 days old. Open the order, then Capture or Cancel. If the bank has already dropped the hold, Capture is refused and the money is not collected.
  • Held card taken, not on the order yet: the plugin recorded the money as taken, but the order does not show the payment yet. The plugin records it on the order by itself once Von Payments confirms the capture and its amount. If the row stays, check the payment in the Von Payments dashboard. If it shows as taken, the money is collected. If it shows as not taken, don't ship until it is captured.
  • Held card taken, Vonpay took a different amount: Von Payments took a different amount than the order recorded, for example after a capture made in the dashboard. Compare the two. Refund what the buyer was overcharged, or collect the rest another way.

Refunds that did not complete (1.3.0 and later)​

When you refund or cancel an order in Medusa, Medusa records the refund at once. Von Payments may accept it and finish it later. The plugin follows each such refund, for a checkout, renewal or offer payment, until Von Payments gives its final answer. If Von Payments completes the refund, nothing shows. If Von Payments cancels or fails it, or has not finished it after two days, the payment comes back here and an error line is logged. Medusa still shows it as refunded, but the shopper may still have the charge.

ActionWhat it does
Check with VonpayReads the refund again. If it is now complete, the row closes. Moves no money.
Refund again…Sends the refund again. It is offered only when Von Payments says the refund never reached the payment provider, or that it failed and no money went back. It is not offered when Von Payments says the refund must not be sent again (the payment was disputed). It checks first, and sends nothing if the refund completed after all or no longer fits the payment.
Mark resolved…Closes the row once you have dealt with it elsewhere. Moves no money, and records your name.

If a failure does not say whether money went back, the row offers no Refund again: check the payment in the Von Payments dashboard first. The plugin never sends a refund again by itself.

The plugin's own refund of an offer payment (a late bank approval, or an item that could not be added) comes back the same way if it fails or is not finished after two days. Refund it in Von Payments, or close the row once you have dealt with it.

The checks run in the plugin's background job, every 10 minutes on the worker. They need npx medusa db:migrate after the update, and the shared Redis locking module (Before you install).