In This Article:
Why do subscription payments fail?
Before we explain why subscription payments fail, we need to understand how Subify creates automated payments.
Let's first get an understanding of these concepts:
Subscription contract:
A subscription contract is an agreement between a customer and a merchant over a specific term for recurring purchases over a set or undefined period of time.A subscription contract is the result of purchasing a selling plan that has recurring policies. After a customer purchases a subscription product or variant at checkout, Shopify generates a subscription contract and shares the contract with Subify using a webhook.
Billing attempt:
A billing attempt represents an attempt to execute a billing cycle and charge the customer payment method for a subscription contract. A subscription is renewed when Subify makes a billing attempt.
When a customer purchases a subscription product, Subify will automatically renew the order on the interval of that product. It means that at every interval, Subify creates a billing attempt for that subscription and sends it to Shopify to process the payment. A billing attempt starts in a pending status. After it has been processed by Shopify, it either transitions to successful or failed:
If the billing attempt is successful, then an order is created with the payment status of "paid".
If the billing attempt fails, then it means that the transaction has failed.
Please note the whole billing and payment processing of subscription contracts (both initial purchases and renewals) is handled by Shopify itself. Please refer to the following table on Shopify.dev:
If the billing attempt fails, we get the error code and error message about that failed billing from Shopify using the "SubscriptionBillingAttempt" object, which you can check its details from Shopify.dev documents:
errorCode
A code corresponding to a payment error during processing.
errorMessage
A message describing a payment error during processing.
We will show the error-code and error-message of a failed payment in the subscription contract detail to the merchants:
Since Shopify handles the billing process directly, we do not have any additional information about why a billing has failed other than the error code and error message.
If there is limited information in the error message or the errors still persist after troubleshooting:
If the error message lacks specific details or contains numerous variables without any context, contact your payment processor support for further assistance:
This is applicable when facing unclear errors such as "Your card was declined," whose cause could occur from various reasons.
Common reasons for subscription payment failure and the action to take about them
You can see the most comon payment failure reasons and the action you can take in the following table.
Since Shopify handles the billing process directly, we do not have any additional information about why a billing has failed other than the error code and error message.
If there is limited information in the error message or the errors still persist after troubleshooting:
If the error message lacks specific details or contains numerous variables without any context, contact your payment processor support for further assistance:
This is applicable when facing unclear errors such as "Your card was declined," whose cause could occur from various reasons.
Payment failure errors | Causes and Actions to take |
Your card has insufficient funds | Contact your customer: |
Your card does not support this type of purchase | The customer needs to use another payment method for their subscription.
|
PAYMENT_METHOD_DECLINED, | The payment method was declined by the processor. |
PAYMENT_METHOD_NOT_FOUND ,
| The payment method revoked indicates that the customer has blocked the payment on their end. This could be through PayPal by canceling the billing agreement or through their credit card company.
The customer should log in and add a new payment method to resolve or cancel this subscription and checkout with a new one using a different payment method.
Send an update payment method email from the subscription contract > "send link update card" button. |
The zip code you supplied failed validation | The customer needs to ensure that the zip code they entered on their order matches what is on file with their credit card company. This failure indicates that it does not. When you enable the Shopify Payments setting to decline charges that fail ZIP code verification, any time the zip code doesn't match, the payment will fail.
It could happen that the customer has moved addresses but still has their old one on file with the credit card company!
To prevent this error, you can either reach out to the customer and ask them to check the zip they have on file or disable this item from your Shopify Setting> payment > In the Shopify Payments section, click Manage. In the Fraud prevention section, uncheck the team in the screenshot. |
How can the customer update their payment method after a failed payment?
Your customer can update their payment method from their customer portal:
You can also send the "card update link" to your customer from the subscription contract page:
1- Go to the subscriptions tab on Subify
2- open the subscription contact of the customer
(you can find the contract by searching the "Subscription ID" that is provided to you in the failed payment notification email)
3- In the payment method section, click on the "Send link to update card" button
An email will be sent to your customer from Shopify to update their card:
They can then fill in their information on the Shopify Payment Method update page, as shown below, and click on "Update Card":
How do I get notified if I have failed payments?
You can enable Subify failed payment notification from Subify's settings, both for you (as the merchant) and for the customer:
Subify will then automatically send an email to both the shop owner and the customer when a payment fails after a certain number of tries. Here is the structure of the email:
You can see all the subscriptions that had failed payments from the Subscriptions tab of your Subify panel > Failed Payment segment:
If you open a subscription contract, you can also check all the billing attempts of that subscription from the Billing History table:
If you hover next to the "Payment fail" tag, you can see the failure reason for each billing attempt:
If there are any retrials for a billing attempt after it failed, you can check them by clicking on the three dots in that row to see more details about the retrials:
You then can see more details about that billing attempt and all its retrials:
How to retry subscriptions after a failed payment?
You can enable Billing Management to eliminate the probability of these payment failures.
By activating Billing management and failed payment notifications, both you and the customer get notified when a payment fails, and then you have time to resolve the failure cause. Subify will then retry charging the customer based on the retrial time you've set on the Billing management setting.
