Payments app — refund session not triggered after captureSessionReject, order still shows as Refunded

[Hariram_M]

Hello,

We operate an offsite payments app and need to understand Shopify’s expected behaviour
when a capture session is rejected. We have merchants who are unable to refund orders,
and we have reproduced the behaviour ourselves on a test store.

This is a question about expected platform behaviour rather than a request to
investigate a specific merchant’s order, so we have described the flow generically.
We can supply store, order and session identifiers privately if you need them to
answer.

BACKGROUND — OUR APP’S BEHAVIOUR

Our payments app settles funds immediately at the payment session stage. It does not
support a separate authorisation-and-capture flow. However, our extension
configuration currently declares both a capture_session_url and a void_session_url,
so merchants who have “Manually capture payment for orders” enabled do receive the
authorisation flow.

When such a merchant’s customer checks out, the sequence is:

1. We receive a payment session with kind “authorization”.
2. We settle the funds immediately — there is no separate capture step on our side.
3. We call paymentSessionResolve. This succeeds with no userErrors.
4. Some minutes later, when the merchant captures, we receive a capture session.
5. Because the funds are already settled and we have no capture step to perform, we
   call captureSessionReject with reason code PROCESSING_ERROR. This also succeeds
   with no userErrors.

We now understand this is the wrong shape for our app, and we intend to remove the
capture and void session URLs so that we only ever receive kind “sale”. That change is
separate from the questions below.

WHAT WE OBSERVED

After the above sequence, when the merchant refunds the order in the Shopify admin:

• We receive NO refund session request at our refund_session_url.
• We receive NO void session request at our void_session_url either.
• The order displays in the admin as Refunded, with the full amount shown as paid
  and then refunded, and a net payment of zero.
• A “Capture payment” button is still shown on the order.

Our refund_session_url is correctly configured and works normally: we have processed
several hundred refund sessions in the same period for orders that arrived as kind
“sale”. The absence is specific to orders that arrived as kind “authorization” and
whose capture session we rejected. Across all such orders on our platform, we have
never once received a refund session.

WE HAVE REPRODUCED THIS

On our own test store we repeated the flow — authorisation-kind payment session,
paymentSessionResolve, then captureSessionReject. The order was subsequently manually
captured and shows as Paid in the admin. Even in that state, no refund session request
was sent to our app when a refund was initiated.

This is the part we cannot explain, and it is the core of our question.

OUR QUESTIONS

1. After a capture session is rejected with captureSessionReject, what state does the
   payment end up in on Shopify’s side? Is the authorisation voided, left open, or
   marked as failed?

2. Why is no refund session sent to the app when the order subsequently displays as
   Paid? Specifically: is the refund session gated on the order’s financial status, or
   on a successfully captured amount recorded against the payment session? If it is
   the latter, does a rejected capture permanently leave the capturable and refundable
   amount at zero, with no way to recover?

3. When a merchant refunds such an order in the admin and no refund session is sent to
   the app, what is Shopify recording? The admin shows a refund that never
   corresponded to any request to us — the funds are still with us and were never
   returned to the customer.

4. Should we have received a void session instead of a refund session in this
   scenario? We received neither.

5. Is there any supported way to recover an order already in this state so that a
   refund session can be issued — for example, by the merchant re-attempting the
   capture, which we would then resolve rather than reject?

6. To confirm our intended fix: if we remove capture_session_url and void_session_url
   from our extension configuration and deploy a new app version, will Shopify send
   kind “sale” for all future payment sessions on all installed stores, including
   stores that have manual capture enabled? And will that release apply automatically
   to existing installs without any merchant action?

[Alan_G]

Hey @Hariram_M - thanks for reaching out.

I checked the expected flow on our end. An authorization should only place a hold, with funds becoming refundable in Shopify after a successful capture. When captureSessionReject succeeds, that specific capture attempt is recorded as failed. It doesn’t automatically void the original authorization, and the rejected capture session can’t later be resolved.

The authorization can remain capturable, which also explains why “Capture payment” may still appear there for you. A new capture attempt should create a new capture session; if your app resolves that new session successfully, the resulting capture should then be eligible for a refund session.

A Shopify Refund record and the payment transaction that moves funds are separate records, so the presence of refund information on an order doesn’t by itself confirm that the provider processed a refund. However, the Refunded financial status you’re seeing still needs investigation, since we’d normally expect that status to be backed by a successful refund transaction. I’d like to trace the specific order and session IDs before confirming exactly what Shopify recorded.. A void would only release the authorization, it wouldn’t return funds your app settled during the authorization step.

The part I’d like to trace is the order that was later shown as Paid but still didn’t produce a refund session. Could you share:

• The store domain, order ID, payment session ID, rejected capture session ID, and any later capture/refund IDs.
• The approximate UTC timestamps and request IDs for the capture rejection, later capture attempt, and refund.
• Whether the later Admin action was Capture payment, Mark as paid, or a new capture session that your app successfully resolved.

If you’d rather share those privately, just let me know and I can set up a DM.

For future payments, removing capture_session_url and void_session_url from an offsite extension indicates that it doesn’t support merchant manual capture, so new payment sessions should use the sale flow. Releasing the new app version replaces the active version served to installed stores and should roll out without merchant action, though it won’t repair existing authorizations already in this state, so happy to look into things for sure.

[Hariram_M]

Hey — thanks a lot for the detailed reply, and apologies for the crossed wires: I also
raised this with Shopify Support over live chat in parallel, and we’ve now got the
scenario cleared up, so no need to spend time tracing the IDs.

For anyone finding this thread later, the conclusion matched what you’ve described:

• captureSessionReject records that capture attempt as failed. It doesn’t convert the
  original authorization into a capture or sale, and a refund needs a successfully
  captured or sale transaction — so a rejected capture leaves no refundable amount.
• The authorization itself isn’t voided and can remain capturable, which is why the
  “Capture payment” button still shows on the order.
• A new capture attempt creates a new capture session, and if the app resolves that
  one successfully, the resulting capture is then eligible for a refund session. That’s
  the recovery path for orders already in this state.
• A Shopify Refund record and the transaction that actually moves funds are separate
  records, so refund information showing on an order doesn’t by itself mean the
  provider processed a refund.
• And for prevention: removing capture_session_url and void_session_url from the
  offsite extension signals no support for merchant manual capture, so new payment
  sessions come through as sale. Releasing the new app version rolls out to installed
  stores without merchant action, though it won’t repair authorizations already in
  this state.

That last point about a new capture session being resolvable is the most useful part
for us — thanks for spelling it out. Appreciate you taking the time.