How to add Shopify's payment update flow to your custom Customer Portal

In your custom customer portal, you may want to route payment method updates through Shopify’s secure, hosted environment rather than collecting card details directly. This keeps your integration PCI compliant and your payment data vaulted in Shopify. This guide covers how to use the Recharge API to send customers to Shopify to update or add a payment method.

This guide covers how to update an existing payment method and add a net new payment method using the Shopify hosted payment flow.

Before you start

• You must have a custom customer portal connected to your Recharge subscriptions and access to the Recharge API. 
• Your portal must be able to authenticate the customer to identify the correct Recharge account.
• This type of customization would be outside of Recharge's scope of Support. If you are not working with a developer currently, Recharge recommends working with a certified Recharge partner to assist with customizations.

How it works

When a customer clicks to update their payment method in your custom portal, your application calls the Recharge API to generate a secure, time-limited URL hosted by Shopify. Your portal then redirects the customer to that URL. Shopify handles all card data collection and tokenization, and the updated method is vaulted directly in Shopify's payment vault and linked back to the customer's Recharge account.

This flow applies to two scenarios:

• Updating an existing payment method: The customer selects a card already on file and is routed to Shopify to replace it.
• Adding a net new payment method: A new card is registered directly in Shopify's vault, bypassing the Recharge vault entirely.

In both cases, your portal calls a Recharge API endpoint with a request body that sets hosted_checkout_url: true. The API returns the redirect URL in the response, and your application performs the redirect. No payment data passes through your portal at any point.

Step 1 – Retrieve the customer's payment method ID

Before generating the redirect URL, you need the unique ID of the payment method the customer wants to update. This is used to target the correct record in Recharge.

1. Query the Recharge API's payment_methods endpoint for the authenticated customer, or use data already loaded in your portal session.
2. Identify the payment_method_id associated with the card the customer has selected to update.

Step 2 – Generate the Shopify hosted URL

Make a POST request to the Recharge API update endpoint for the selected payment method. The request body instructs Recharge to return a hosted Shopify URL instead of processing the update directly.

1. Send the following POST request from your portal's backend: 
   
   Method and endpoint:
   POST /customers/{customer_id}/payment_methods/{payment_method_id}/update 
   
   Request body:

   {
     "payment_method": {
       "hosted_checkout_url": true
     }
   }

2. On success, the API returns a 200 OK response containing the redirect URL. Here is an example of a successful response.

   {
     "success": true,
     "payment_method": {
       "hosted_checkout_url": "https://{shop_domain}/1234567/update_payment_method/{unique_token}"
     }
   }

3. Extract the hosted_checkout_url value from the response.

Image: [Screenshot of a sample API response in a developer tool, with the hosted_checkout_url value highlighted]

Step 3 – Redirect the customer

Once you have the URL, redirect the customer's browser to it immediately. The customer will leave your portal and enter Shopify's secure payment page to complete the update.

1. Perform a client-side or server-side redirect (HTTP 302 or equivalent) to the hosted_checkout_url returned in the API response.
2. Before redirecting, display a brief message to set the customer's expectation — for example: "You're being securely redirected to our payment processor to update your billing details."

Step 4 – Handle the return flow

After the customer completes or cancels the payment update on Shopify's page, they are redirected back to your portal via the Return URL configured in your Recharge account settings.

1. Ensure the Return URL in your Recharge account points to the correct section of your custom portal (for example, the payment methods page).
2. When the customer lands back in your portal, refresh the payment method list by re-querying the Recharge API's payment_methods endpoint. This ensures the updated card details are displayed.
3. If the API call in Step 2 fails, display a user-friendly error message and advise the customer to contact support. Common causes include incorrect authentication or an invalid payment method ID.

Adding a net new payment method

If you need to add a brand new payment method rather than update an existing one — for example, when a customer's current card is vaulted in Recharge and you want the replacement to be vaulted directly in Shopify — use the payment method creation endpoint instead.

1. Send the following POST request: 
   
   Method and endpoint:
   POST /customers/{customer_id}/payment_methods 
   
   Request body:

   {
     "payment_method": {
       "hosted_checkout_url": true
     }
   }

2. On success, the API returns a 200 OK response:

   {
     "success": true,
     "payment_method": {
       "hosted_checkout_url": "https://{shop_domain}/7890123/add_payment_method/{unique_token}"
     }
   }

3. Extract the hosted_checkout_url and redirect the customer immediately, following the same steps in Step 3 and Step 4 above.

When the customer completes this flow, the new payment method is vaulted in Shopify and linked to their Recharge account.

Considerations

Consider the following before setting up this flow.