How to customize portal URLs for Stripe and GoCardless
November 13, 2024
This guide explains how to customize the portal URLs for Stripe and GoCardless contacts to control payment method flows and redirects. Portal URLs allow your customers to manage their payment methods and perform other operations through a dedicated UI.
Before you begin
This guide assumes you have:
- A basic understanding of the Unified API
- An active integration with either Stripe or GoCardless
Understanding portal URLs
When working with the accounting_contact object for Stripe and GoCardless integrations, each contact includes a portal_url field. This URL provides access to the contact's portal UI where they can perform various operations, such as managing payment methods.
For example, a typical response might look like:
{
"id": 77558,
"portal_url": "<https://api.unified.to/accounting/{connection_id}/contact/{contact_id}/portal>"
}
Customize the portal URL
You can customize the portal URL's behaviour by appending specific query parameters to your API calls. The following parameters are available:
success_url(optional): Specifies where users should be redirected after completing their actiontype(optional): Specifies the type of action the link is intended for. Available values:portal: Generates a standard portal UI link (default)add_payment_method: Generates a portal UI URL specifically for adding a new payment method
Add a payment method with custom redirect
To create a URL that allows customers to add a payment method and redirects them upon completion:
- Start with the original portal URL from the contact object:
https://api.unified.to/accounting/{connection_id}/contact/{contact_id}/portal - Append the
success_urlandtypeparameters:https://api.unified.to/accounting/{connection_id}/contact/{contact_id}/portal?success_url=YOUR_REDIRECT_URL&type=add_payment_method
Note: Both success_url and type parameters are optional. If type is not specified, the system defaults to type=portal.