GoCardlessDeveloper Docs
Create a sandbox account

Scheme Identifier

View as Markdown

This represents a scheme identifier (e.g. a SUN in Bacs or a CID in SEPA). Scheme identifiers are used to specify the beneficiary name that appears on customers' bank statements.

Create a scheme identifier#

POST/scheme_identifiers

Creates a new scheme identifier. 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.

Scheme identifier name validations

The name field of a scheme identifier can contain alphanumeric characters, spaces and special characters.

Its maximum length and the special characters it supports depend on the scheme:

schememaximum lengthspecial characters allowed
bacs18 characters/ . & -
sepa70 characters/ ? : ( ) . , + & < > ' "
ach16 characters/ ? : ( ) . , ' + -
faster_payments18 characters/ ? : ( ) . , ' + -

The validation error that gets returned for an invalid name will contain a suggested name in the metadata that is guaranteed to pass name validations.

You should ensure that the name you set matches the legal name or the trading name of the creditor, otherwise, there is an increased risk of chargeback.

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",
      "reference": "REF123",
      "status": "pending",
      "minimum_advance_notice": 3,
      "can_specify_mandate_reference": false,
      "currency": "GBP",
      "address_line1": "65 Goswell Road",
      "address_line2": null,
      "address_line3": null,
      "city": "London",
      "region": null,
      "postal_code": "EC1V 7EN",
      "country_code": "GB",
      "email": "name@example.com",
      "phone_number": "+44 20 8338 9540"
  }
}
@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"
    }
})
const schemeIdentifier = await client.schemeIdentifiers.create({
  scheme: "bacs",
  name: "The Wine Club",
  links: {
    creditor: "CR123"
  }
});
$client->schemeIdentifiers()->create([
  'params' => ['scheme' => 'bacs',
              'name' => 'Example Ltd',
              'links' => ['creditor' => 'CR123']
  ]
]);
import com.gocardless.services.SchemeIdentifierService.SchemeIdentifierCreateRequest.Scheme;

SchemeIdentifier schemeIdentifier = client.schemeIdentifiers().create()
  .withScheme(Scheme.BACS)
  .withName("The Wine Club")
  .withLinksCreditor("CR123")
  .execute();
schemeIdentifierCreateParams := gocardless.SchemeIdentifierCreateParams{
  Name:   "Durian Co",
  Scheme: "bacs",
  Links: &gocardless.SchemeIdentifierCreateParamsLinks{
    Creditor: "CR123",
  },
}
schemeIdentifier, err := client.SchemeIdentifiers.Create(ctx, schemeIdentifierCreateParams)
if err != nil {
  fmt.Printf("error creating scheme identifier: %s", err.Error())
  return
}
var schemeIdentifierRequest = new GoCardless.Services.SchemeIdentifierCreateRequest
{
    Name = "The Wine Club",
    Scheme = GoCardless.Services.SchemeIdentifierCreateRequest.SchemeIdentifierScheme.Bacs,
    Links = new GoCardless.Services.SchemeIdentifierCreateRequest.SchemeIdentifierLinks()
    {
        Creditor = "CR123"
    }
};

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

GoCardless.Resources.SchemeIdentifier schemeIdentifier = schemeIdentifierResponse.SchemeIdentifier;
Request Body
scheme_identifiersobject
3 properties
namestring

The name which appears on customers' bank statements. This should usually be the merchant's trading name.

schemestring

The scheme which this scheme identifier applies to.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepasepa_credit_transfersepa_instant_credit_transfer
linksobject
1 properties
creditorstring

required ID of the associated creditor.

Response 201

Resource created successfully

scheme_identifiersobject
18 properties
idstring

Unique identifier, usually beginning with "SU".

created_atstring

Fixed timestamp, recording when this resource was created.

namestring

The name which appears on customers' bank statements. This should usually be the merchant's trading name.

schemestring

The scheme which this scheme identifier applies to.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepasepa_credit_transfersepa_instant_credit_transfer
referencestring

The scheme-unique identifier against which payments are submitted.

statusstring

The status of the scheme identifier. Only active scheme identifiers will be applied to a creditor and used against payments.

pendingactive
minimum_advance_noticeinteger

The minimum interval, in working days, between the sending of a pre-notification to the customer, and the charge date of a payment using this scheme identifier.

By default, GoCardless sends these notifications automatically. Please see our compliance requirements for more details.

can_specify_mandate_referenceboolean

Whether a custom reference can be submitted for mandates using this scheme identifier.

currencystring

The currency of the scheme identifier.

AUDCADDKKEURGBPNZDSEKUSD
address_line1string

The first line of the scheme identifier's support address.

address_line2string

The second line of the scheme identifier's support address.

address_line3string

The third line of the scheme identifier's support address.

citystring

The city of the scheme identifier's support address.

regionstring

The scheme identifier's support address region, county or department.

postal_codestring

The scheme identifier's support postal code.

country_codestring
emailstring

Scheme identifier's support email address.

phone_numberstring

Scheme identifier's support phone number.

Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject

List scheme identifiers#

GET/scheme_identifiers

Returns a cursor-paginated list of your scheme identifiers.

GET https://api.gocardless.com/scheme_identifiers HTTP/1.1
@client.scheme_identifiers.list.records
client.scheme_identifiers.list().records
const schemeIdentifierList = await client.schemeIdentifiers.list();
$client->schemeIdentifiers()->list()->records;
for (SchemeIdentifier schemeIdentifier: client.schemeIdentifiers().all().execute()) {
  System.out.println(schemeIdentifier.getId());
}
schemeIdentifierListParams := gocardless.SchemeIdentifierListParams{}

schemeIdentifeirListResult, err := client.SchemeIdentifiers.List(ctx, schemeIdentifierListParams)
if err != nil {
  fmt.Printf("error listing scheme identifiers: %s", err.Error())
  return
}
for _, schemeIdentifier := range schemeIdentifeirListResult.SchemeIdentifiers {
  fmt.Println(schemeIdentifier.Id)
}
var schemeIdentifierListResponse = client.SchemeIdentifiers.All();

foreach (GoCardless.Resources.SchemeIdentifier schemeIdentifier in schemeIdentifierListResponse)
{
    Console.WriteLine(schemeIdentifier.Id);
}
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "scheme_identifiers": [
    {
      "id": "SU123",
      "created_at": "2021-01-23T09:41:36.234Z",
      "name": "The Wine Club",
      "scheme": "bacs",
      "reference": "REF123",
      "status": "active",
      "minimum_advance_notice": 3,
      "can_specify_mandate_reference": false,
      "currency": "GBP",
      "address_line1": "65 Goswell Road",
      "address_line2": null,
      "address_line3": null,
      "city": "London",
      "region": null,
      "postal_code": "EC1V 7EN",
      "country_code": "GB",
      "email": "name@example.com",
      "phone_number": "+44 20 8338 9540"
    }
  ],
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  }
}
Response 200

Successful response

scheme_identifiersarray
18 properties
idstring

Unique identifier, usually beginning with "SU".

created_atstring

Fixed timestamp, recording when this resource was created.

namestring

The name which appears on customers' bank statements. This should usually be the merchant's trading name.

schemestring

The scheme which this scheme identifier applies to.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepasepa_credit_transfersepa_instant_credit_transfer
referencestring

The scheme-unique identifier against which payments are submitted.

statusstring

The status of the scheme identifier. Only active scheme identifiers will be applied to a creditor and used against payments.

pendingactive
minimum_advance_noticeinteger

The minimum interval, in working days, between the sending of a pre-notification to the customer, and the charge date of a payment using this scheme identifier.

By default, GoCardless sends these notifications automatically. Please see our compliance requirements for more details.

can_specify_mandate_referenceboolean

Whether a custom reference can be submitted for mandates using this scheme identifier.

currencystring

The currency of the scheme identifier.

AUDCADDKKEURGBPNZDSEKUSD
address_line1string

The first line of the scheme identifier's support address.

address_line2string

The second line of the scheme identifier's support address.

address_line3string

The third line of the scheme identifier's support address.

citystring

The city of the scheme identifier's support address.

regionstring

The scheme identifier's support address region, county or department.

postal_codestring

The scheme identifier's support postal code.

country_codestring
emailstring

Scheme identifier's support email address.

phone_numberstring

Scheme identifier's support phone number.

metaobject
2 properties
limitinteger
cursorsobject
2 properties
beforestring

Cursor pointing to the end of the desired set.

afterstring

Cursor pointing to the start of the desired set.

Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject

Get a single scheme identifier#

GET/scheme_identifiers/{scheme_identifier_id}

Retrieves the details of an existing scheme identifier.

Path Parameters

NameTypeDescription
scheme_identifier_idrequiredstring

The scheme identifier id

GET https://api.gocardless.com/scheme_identifiers/SU123 HTTP/1.1
@client.scheme_identifiers.get("SU123")
client.scheme_identifiers.get("SU123").attributes
const schemeIdentifier = await client.schemeIdentifiers.find("SU123");
$client->schemeIdentifiers()->get('SU123');
SchemeIdentifier schemeIdentifier = client.schemeIdentifiers().get("SU123").execute();
schemeIdentifier, err := client.SchemeIdentifiers.Get(ctx, "SU123")
if err != nil {
  fmt.Printf("error getting scheme identifier: %s", err.Error())
  return
}
var schemeIdentifierResponse = await client.SchemeIdentifiers.GetAsync("SU123");

GoCardless.Resources.SchemeIdentifier schemeIdentifier = schemeIdentifierResponse.SchemeIdentifier;
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "scheme_identifiers": {
    "id": "SU123",
    "created_at": "2021-01-23T09:41:36.234Z",
    "name": "The Wine Club",
    "scheme": "bacs",
    "reference": "REF123",
    "status": "active",
    "minimum_advance_notice": 3,
    "can_specify_mandate_reference": false,
    "currency": "GBP",
    "address_line1": "65 Goswell Road",
    "address_line2": null,
    "address_line3": null,
    "city": "London",
    "region": null,
    "postal_code": "EC1V 7EN",
    "country_code": "GB",
    "email": "name@example.com",
    "phone_number": "+44 20 8338 9540"
  }
}
Response 200

Successful response

scheme_identifiersobject
18 properties
idstring

Unique identifier, usually beginning with "SU".

created_atstring

Fixed timestamp, recording when this resource was created.

namestring

The name which appears on customers' bank statements. This should usually be the merchant's trading name.

schemestring

The scheme which this scheme identifier applies to.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepasepa_credit_transfersepa_instant_credit_transfer
referencestring

The scheme-unique identifier against which payments are submitted.

statusstring

The status of the scheme identifier. Only active scheme identifiers will be applied to a creditor and used against payments.

pendingactive
minimum_advance_noticeinteger

The minimum interval, in working days, between the sending of a pre-notification to the customer, and the charge date of a payment using this scheme identifier.

By default, GoCardless sends these notifications automatically. Please see our compliance requirements for more details.

can_specify_mandate_referenceboolean

Whether a custom reference can be submitted for mandates using this scheme identifier.

currencystring

The currency of the scheme identifier.

AUDCADDKKEURGBPNZDSEKUSD
address_line1string

The first line of the scheme identifier's support address.

address_line2string

The second line of the scheme identifier's support address.

address_line3string

The third line of the scheme identifier's support address.

citystring

The city of the scheme identifier's support address.

regionstring

The scheme identifier's support address region, county or department.

postal_codestring

The scheme identifier's support postal code.

country_codestring
emailstring

Scheme identifier's support email address.

phone_numberstring

Scheme identifier's support phone number.

Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject