[Sales Channel] Async Order Payment Failure

Shopify Partner
17 0 0



We are facing an issue where after hitting `checkouts/${id}/payments.json` we do not get a message back about the status of the payment. We don't know if it actually succeeded or not. The docs do not say that it's asynchronous and actually allude to it being synchronous since it can return immediate failures due to processing. Overall, it's very obtuse and has led to frustration with our users. 


Immediately after hitting the route with a card that is destined to be declined, we get "null" for payment processing errors.


How do we know if a payment failed?


There exists an "order/paid" webhook topic, but from my understanding, this won't fire if the payment failed.


When using stripe directly, we know in a synchronous manner if the payment failed or succeeded. This is the experience we, and a lot of others likely expect.


Ideally, we don't have to restructure our checkout flow just to account for this shopify behaviour. So this begs the question: How do we know if a payment failed at the time of payment?


Screen Shot 2021-10-04 at 4.01.04 PM.png

Replies 2 (2)

Shopify Partner
17 0 0

@Luke_K any thoughts on this?

Shopify Staff
402 66 100

Hey @almax120 

So, the payment_processing_error_message is a property on the payments object that is returned by the gateway in question to Shopify and can be null if one is not provided. please see here

One idea could be to poll the checkout token using payments.json to see the transaction status that is returned(docs). 

Nested within the payments object, there would be a transaction object holding the status. This status is either success or failure (docs).  

Running some tests today on payment.json endpoint, I see that although payment_processing_error_message can be null, within the transactions object we will see (object pruned for brevity) :


"payments": [
"payment_processing_error_message": null,
"transaction": {
"status": "success",


I can confirm that yes, orders/paid hook wouldn't fire in the event of a failed transaction. 

I do appreciate that the above is a bit more work though, and I've raised this point internally with the custodians of the payments.json endpoint. 

If there's any update at all, we'll communicate any updates on the Shopify Community forums or via the Developer Changelog. Hope that helps!


| Shopify |
- Was my reply helpful? Click Like to let me know!
- Was your question answered? Mark it as an Accepted Solution!