GoCardlessDeveloper Docs
Create a sandbox account

Setting Up Branding#

View as Markdown

If you are using the GoCardless Hosted Payment Pages or the Javascript Drop-in, you can customise the look and feel of your merchants' payment pages and notification emails by adding a logo or setting the colour theme.

How branding is applied to your merchants#

All your merchants (represented as creditors in GoCardless) start off without any custom branding.

If you add branding to your primary creditor, the customisation settings will be inherited by all your creditors. This means if you want all your merchants to have the same branding, you only need to configure this once against your primary creditor.

If you add branding to a specific creditor, this will override the primary creditor settings for that creditor. This means if merchant X wants to have their own branding, you can apply it to their creditor and their logo and colour themes will appear to that merchant's customers only.

How to set up custom branding#

Dashboard#

To do this in the dashboard and preview what the page will look like:

  • Navigate to the creditor you want to update
  • Click Update branding in the top right corner
  • Upload a logo for the creditor
  • Customise the payment page's colours

API#

To do this using the GoCardless API, you can use the following steps:

POST /branding/logos#

You can upload a logo to a creditor by performing a POST request to the /branding/logos endpoint. If a creditor already has a logo, this will update the existing logo linked to the creditor. The required parameters are:

ParameterDescription
imageBase64 encoded string of the image to be uploaded. Must be in the format "data:{image/type};base64,{base64 encoded string}". Max file size is 0.5MB.
links[creditor]ID of the creditor the logo belongs to.

Examples of how to make this request using the GoCardless client libraries:

POST https://api.gocardless.com/branding/logos HTTP/1.1
Content-Type: application/json
{
  "logos": {
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
    "links": {
      "creditor": "CR123"
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/json
{
  "logos": {
    "id": "LO123"
  }
}
curl --silent \
  -H "Content-Type: application/json" \
  -H "Gocardless-Version: 2015-07-06" \
  -H "Authorization: Bearer ${API_ACCESS_TOKEN}" \
  "https://api.gocardless.com/branding/logos" \
  -d @- << EOF
{
  "logos": {
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
    "links": {
      "creditor": "CR123"
    }
  }
}
EOF
$client->logos()->createForCreditor([
  "params" => [
    "image" => "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
    "links" => [
      "creditor" => "CR123"
    ]
  ]
]);
client.logos.create_for_creditor(params={
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
    "links": {
        "creditor": "CR123"
    }
})
@client.logos.create_for_creditor(
  params: {
    image: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
    links: {
      creditor: "CR123"
    }
  }
)
Logo logo = client.logos().createForCreditor()
    .withImage("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA")
    .withLinksCreditor("CR123")
    .execute();
const logo = await client.logos.createForCreditor({
  image:
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
  links: {
    creditor: "CR123",
  },
});
var logoCreateForCreditorRequest = new GoCardless.Services.LogoCreateForCreditorRequest()
{
    Image = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
    Links = new GoCardless.Services.LogoCreateForCreditorRequest.LogoLinks()
    {
        Creditor = "CR0123"
    }
};

var logoCreateForCreditorResponse = await gocardless.Logos.CreateForCreditorAsync(logoCreateForCreditorRequest);
GoCardless.Resources.Logo creditorLogo = logoCreateForCreditorResponse.LogoResponse;
package main

import (
	gocardless "github.com/gocardless/gocardless-pro-go/v6"
)

accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
}
client, err := gocardless.New(config)
if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
}

logoCreateForCreditorParams := gocardless.LogoCreateForCreditorParams{
    Image: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
    Links: gocardless.LogoCreateForCreditorParamsLinks{
        Creditor: "CR123",
    },
}

logo, err := client.Logos.CreateForCreditor(context, logoCreateForCreditorParams)

For more details, see the API reference docs for creating logos.

POST /branding/payer_themes#

You can add payer colour themes to a creditor's branding by performing a POST request to the /branding/payer_themes endpoint. If a creditor already has payer themes, this will update the existing payer theme linked to the creditor. The required parameters are:

ParametersDescription
button_background_colourThe hexcode colour for button background
content_box_border_colourThe hexcode colour for for content box borders
header_background_colourThe hexcode colour for the header background
link_text_colourThe hexcode colour for text links
links[creditor]ID of the creditor the payer theme belongs to.

Examples of how to make this request using the GoCardless client libraries:

POST https://api.gocardless.com/branding/payer_themes HTTP/1.1
Content-Type: application/json
{
  "payer_themes": {
    "header_background_colour": "#BD10E0",
    "link_text_colour": "#7ED321",
    "button_background_colour": "#128DAA",
    "content_box_border_colour": "#BD10E0",
    "links": {
      "creditor": "CR123"
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/json
{
  "payer_themes": {
    "id": "PTH123"
  }
}
curl --silent \
  -H "Content-Type: application/json" \
  -H "Gocardless-Version: 2015-07-06" \
  -H "Authorization: Bearer ${API_ACCESS_TOKEN}" \
  "https://api.gocardless.com/branding/logos" \
  -d @- << EOF
{
  "payer_themes": {
    "header_background_colour": "#BD10E0",
    "link_text_colour": "#7ED321",
    "button_background_colour": "#128DAA",
    "content_box_border_colour": "#BD10E0",
    "links": {
      "creditor": "CR123"
    }
  }
}
EOF
$client->payerThemes()->createForCreditor([
  "params" => [
    "header_background_colour" => "#BD10E0",
    "link_text_colour" => "#7ED321",
    "button_background_colour" => "#128DAA",
    "content_box_border_colour" => "#BD10E0",
    "links" => [
      "creditor" => "CR123"
    ]
  ]
]);
client.payer_themes.create_for_creditor(params={
    "header_background_colour": "#BD10E0",
    "link_text_colour": "#7ED321",
    "button_background_colour": "#128DAA",
    "content_box_border_colour": "#BD10E0",
    "links": {
        "creditor": "CR123"
    }
})
@client.payer_themes.create_for_creditor(
  params: {
    "header_background_colour": "#BD10E0",
    "link_text_colour": "#7ED321",
    "button_background_colour": "#128DAA",
    "content_box_border_colour": "#BD10E0",
    "links": {
      "creditor": "CR123"
    }
  }
)
PayerTheme payerTheme = client.payerThemes().createForCreditor()
    .withButtonBackgroundColour("#128DAA")
    .withContentBoxBorderColour("#BD10E0")
    .withHeaderBackgroundColour("#BD10E0")
    .withLinkTextColour("#7ED321")
    .withLinksCreditor("CR123")
    .execute();
const payerThemes = await client.payerThemes.createForCreditor({
  header_background_colour: "#BD10E0",
  link_text_colour: "#7ED321",
  button_background_colour: "#128DAA",
  content_box_border_colour: "#BD10E0",
  links: {
    creditor: "CR123",
  },
});
var payerThemeCreateForCreditorRequest = new GoCardless.Services.PayerThemeCreateForCreditorRequest()
{
    HeaderBackgroundColour = "#BD10E0",
    LinkTextColour = "#7ED321",
    ButtonBackgroundColour = "#128DAA",
    ContentBoxBorderColour = "#BD10E0",
    Links = new GoCardless.Services.PayerThemeCreateForCreditorRequest.PayerThemeLinks()
    {
        Creditor = "CR0123"
    }
};

var payerThemeCreateForCreditorResponse = await gocardless.PayerThemes.CreateForCreditorAsync(payerThemeCreateForCreditorRequest);
GoCardless.Resources.PayerTheme creditorPayerTheme = payerThemeCreateForCreditorResponse.PayerThemeResponse;
package main

import (
	gocardless "github.com/gocardless/gocardless-pro-go/v6"
)

accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
    fmt.Printf("got err in initialising config: %s", err.Error())
    return
}
client, err := gocardless.New(config)
if err != nil {
    fmt.Println("error in initialisating client: %s", err.Error())
    return
}

payerThemeCreateForCreditorParams := gocardless.PayerThemeCreateForCreditorParams{
    ButtonBackgroundColour: "#128DAA",
    ContentBoxBorderColour: "#BD10E0",
    HeaderBackgroundColour: "#BD10E0",
    LinkTextColour: "#7ED321",
    Links: gocardless.PayerThemeCreateForCreditorParamsLinks{
        Creditor: "CR123",
    },
}

payerThemes, err := client.PayerThemes.CreateForCreditor(context, payerThemeCreateForCreditorParams)

For more details, see the API reference docs for creating payer themes.

Here are a few tips to help make your logo looks great across your customer payment page and notification emails.

We support JPG and PNG formats. Your logo will be scaled to a maximum of 300px by 40px.

Use a rectangular format
Use a rectangular format

Rectangular logos display best. Square logos will appear smaller and may be harder for your customers to read.

Crop tightly
Crop tightly

Crop your logo tightly with minimal extra space to make it appear as large as possible.

Use a solid background
Use a solid background

Save your logo on a solid background colour. Avoid photography or multiple colours within your logo.

Ensure good contrast
Ensure good contrast

Make sure the background colour contrasts well with your logo so your customers can clearly see it.

Keep it concise
Keep it concise

Avoid unnecessary words and taglines to keep your logo easy to read.

Use transparent PNG
Use transparent PNG

Save your logo as a transparent PNG file. This way, you can easily change the background colour independently.

What's next?#

API Request Signing

Add an extra layer of security by signing your API requests with ECDSA keys.

Learn more
Bank Details Access

Access encrypted bank account details for your customers.

Learn more
SupportDashboard