GoCardlessDeveloper Docs
Create a sandbox account

Setting a Scheme Identifier#

View as Markdown

In this step of the GoCardless Embed guide, you will create a scheme identifier for a given creditor.

In order for your merchant's name to appear on their payers' bank statements, you will need to request custom scheme identifiers.

Different schemes have different scheme identifiers (e.g. SUNs in Bacs and CIDs in SEPA). Therefore you must request a scheme identifier for each scheme you plan to collect payments in.

Creating a scheme identifier#

You can create a scheme identifier by performing a POST request to the /scheme_identifiers endpoint. The required parameters are:

ParameterDescription
nameThe name which will appear on the payer's bank statement. This will usually be the merchant's trading name.
schemeThe scheme which this scheme identifier applies to. The supported schemes for the GoCardless Embed product are: bacs (UK direct debit), faster_payments (UK Pay By Banks), sepa_core (Eurozone direct debit), and ach (US direct debit).
links[creditor]The ID of the creditor to link the scheme identifier to. Creditors start with 'CR'

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

POST https://api.gocardless.com/scheme_identifiers HTTP/1.1
Content-Type: application/json
{
"scheme_identifiers": {
  "name": "The Wine Club",
  "scheme": "bacs",
  "links": {
      "creditor": "CR123"
  }
}
}

HTTP/1.1 201 Created
Location: /scheme_identifiers/SU123
Content-Type: application/json
{
"scheme_identifiers": {
"id": "SU123",
"created_at": "2021-01-23T13:44:19.006Z",
"name": "The Wine Club",
"scheme": "bacs",
"status": "pending",
"currency": "GBP",
...
},
}
$client->schemeIdentifiers()->create([
'params' => [
'scheme' => 'bacs',
'name' => 'Example Ltd'
'links' => ['creditor' => 'CR123']]
]
]);
client.scheme_identifiers.create(params={
"scheme": "bacs",
"name": "Example Ltd",
"links": {
"creditor": "CR123"
}
})
@client.scheme_identifiers.create(
params: {
scheme: "bacs",
name: "Example Ltd",
links: {
creditor: "CR123"
}
}
)
SchemeIdentifier schemeIdentifier = client.schemeIdentifiers().create()
.withScheme(SchemeIdentifierService.SchemeIdentifierCreateRequest.Scheme.BACS)
.withName("The Wine Club")
.withLinksCreditor("CR123")
.execute();
const schemeIdentifier = await client.schemeIdentifiers.create({
scheme: "bacs",
name: "The Wine Club",
links: {
creditor: "CR123",
},
});
SchemeIdentifierCreateRequest schemeIdentifierRequest = new SchemeIdentifierCreateRequest
{
Name = "The Wine Club",
Scheme = SchemeIdentifierCreateRequest.SchemeIdentifierScheme.Bacs,
Links = new SchemeIdentifierCreateRequest.SchemeIdentifierLinks()
{
Creditor = "CR0123"
}
};

var schemeIdentifierResponse = await client.SchemeIdentifiers.CreateAsync(schemeIdentifierRequest);

GoCardless.Resources.SchemeIdentifier schemeIdentifier = schemeIdentifierResponse.SchemeIdentifier;
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
}

context := context.Background()
schemeIdentifierCreateParams := gocardless.SchemeIdentifierCreateParams{
Name: "Durian Co",
Scheme: "bacs",
Links: gocardless.SchemeIdentifierCreateParamsLinks{
Creditor: "CR123",
},
}
schemeIdentifier, err := client.SchemeIdentifiers.Create(context, schemeIdentifierCreateParams)
if err != nil {
fmt.Printf("error creating scheme identifier: %s", err.Error())
return
}
curl --silent \
-H "Content-Type: application/json" \
-H "Gocardless-Version: 2015-07-06" \
-H "Authorization: Bearer ${API_ACCESS_TOKEN}" \
"https://api.gocardless.com/scheme_identifiers" \
-d @- << EOF
{
"scheme_identifiers": {
"name": "The Wine Club",
"scheme": "bacs",
"links": {
"creditor": "CR123"
}
}
}
EOF

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

Scheme identifier status#

The scheme identifier status will be pending while GoCardless is processing the request. Once the scheme identifier is ready to be used the status will be updated to active. At this point, GoCardless will emit a scheme identifier activated event via webhook to notify you of this change.

In Bacs, it will take up to five working days for a scheme identifier to become active. On other schemes, including SEPA, this happens instantly.

What's next?#

Setting Up Mandates & Payments

Use Billing Requests to set up Direct Debit mandates and collect payments from your customers.

Learn more
API Reference: Scheme Identifiers

Full reference documentation for the Scheme Identifiers API.

Learn more
SupportDashboard