Unified.to
Blog

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:

  1. success_url (optional): Specifies where users should be redirected after completing their action
  2. type (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:

  1. Start with the original portal URL from the contact object:
    https://api.unified.to/accounting/{connection_id}/contact/{contact_id}/portal
  2. Append the success_url and type parameters:
    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.

See also

Blog