Scheme Identifier
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#
/scheme_identifiersCreates 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:
| scheme | maximum length | special characters allowed |
|---|---|---|
bacs | 18 characters | / . & - |
sepa | 70 characters | / ? : ( ) . , + & < > ' " |
ach | 16 characters | / ? : ( ) . , ' + - |
faster_payments | 18 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.
Request Body
scheme_identifiersobject3 properties
namestringrequired
The name which appears on customers' bank statements. This should usually be the merchant's trading name.
schemeenumrequired
The scheme which this scheme identifier applies to.
achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepasepa_credit_transfersepa_instant_credit_transferlinksobject
1 properties
creditorstring
required ID of the associated creditor.
Response 201
Resource created successfully
scheme_identifiersobject18 properties
idstringrequired
Unique identifier, usually beginning with "SU".
created_atstringrequired
Fixed timestamp, recording when this resource was created.
namestringrequired
The name which appears on customers' bank statements. This should usually be the merchant's trading name.
schemeenumrequired
The scheme which this scheme identifier applies to.
achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepasepa_credit_transfersepa_instant_credit_transferreferencestring | nullrequired
The scheme-unique identifier against which payments are submitted.
statusenumrequired
The status of the scheme identifier. Only active scheme identifiers will be applied to a creditor and used against payments.
pendingactiveminimum_advance_noticeintegerrequired
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_referencebooleanrequired
Whether a custom reference can be submitted for mandates using this scheme identifier.
currencyenumrequired
The currency of the scheme identifier.
AUDCADDKKEURGBPNZDSEKUSDaddress_line1string | nullrequired
The first line of the scheme identifier's support address.
address_line2string | nullrequired
The second line of the scheme identifier's support address.
address_line3string | nullrequired
The third line of the scheme identifier's support address.
citystring | nullrequired
The city of the scheme identifier's support address.
regionstring | nullrequired
The scheme identifier's support address region, county or department.
postal_codestring | nullrequired
The scheme identifier's support postal code.
country_codestring | nullrequired
emailstring | nullrequired
Scheme identifier's support email address.
phone_numberstring | nullrequired
Scheme identifier's support phone number.
Errors 400401404422500
Bad Request
Unauthorised
Not found
Validation Error
Internal Error
Error Body
errorobjectrequiredGeneric error
6 properties
codeintegerdocumentation_urlstringerrorsarrayrequired
6 properties
reasonstringfieldstringrequest_pointerstringmessagestringrequiredmetadataobjectlinksobjectmessagestringrequiredrequest_idstringrequiredtypestringList scheme identifiers#
/scheme_identifiersReturns a cursor-paginated list of your scheme identifiers.
Query Parameters
| Name | Type | Description |
|---|---|---|
before | string | null | Cursor pointing to the end of the desired set. |
after | string | null | Cursor pointing to the start of the desired set. |
limit | integer | string | Number of records to return. |
creditor | string | Unique identifier, beginning with "CR". |
Response 200
Successful response
scheme_identifiersarray18 properties
idstringrequired
Unique identifier, usually beginning with "SU".
created_atstringrequired
Fixed timestamp, recording when this resource was created.
namestringrequired
The name which appears on customers' bank statements. This should usually be the merchant's trading name.
schemeenumrequired
The scheme which this scheme identifier applies to.
achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepasepa_credit_transfersepa_instant_credit_transferreferencestring | nullrequired
The scheme-unique identifier against which payments are submitted.
statusenumrequired
The status of the scheme identifier. Only active scheme identifiers will be applied to a creditor and used against payments.
pendingactiveminimum_advance_noticeintegerrequired
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_referencebooleanrequired
Whether a custom reference can be submitted for mandates using this scheme identifier.
currencyenumrequired
The currency of the scheme identifier.
AUDCADDKKEURGBPNZDSEKUSDaddress_line1string | nullrequired
The first line of the scheme identifier's support address.
address_line2string | nullrequired
The second line of the scheme identifier's support address.
address_line3string | nullrequired
The third line of the scheme identifier's support address.
citystring | nullrequired
The city of the scheme identifier's support address.
regionstring | nullrequired
The scheme identifier's support address region, county or department.
postal_codestring | nullrequired
The scheme identifier's support postal code.
country_codestring | nullrequired
emailstring | nullrequired
Scheme identifier's support email address.
phone_numberstring | nullrequired
Scheme identifier's support phone number.
metaobject2 properties
limitintegerrequiredcursorsobjectrequired
2 properties
beforestring | nullrequired
Cursor pointing to the end of the desired set.
afterstring | nullrequired
Cursor pointing to the start of the desired set.
Errors 400401404422500
Bad Request
Unauthorised
Not found
Validation Error
Internal Error
Error Body
errorobjectrequiredGeneric error
6 properties
codeintegerdocumentation_urlstringerrorsarrayrequired
6 properties
reasonstringfieldstringrequest_pointerstringmessagestringrequiredmetadataobjectlinksobjectmessagestringrequiredrequest_idstringrequiredtypestringGet a single scheme identifier#
/scheme_identifiers/{scheme_identifier_id}Retrieves the details of an existing scheme identifier.
Path Parameters
| Name | Type | Description |
|---|---|---|
scheme_identifier_id | stringrequired | The scheme identifier id |
Response 200
Successful response
scheme_identifiersobject18 properties
idstringrequired
Unique identifier, usually beginning with "SU".
created_atstringrequired
Fixed timestamp, recording when this resource was created.
namestringrequired
The name which appears on customers' bank statements. This should usually be the merchant's trading name.
schemeenumrequired
The scheme which this scheme identifier applies to.
achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepasepa_credit_transfersepa_instant_credit_transferreferencestring | nullrequired
The scheme-unique identifier against which payments are submitted.
statusenumrequired
The status of the scheme identifier. Only active scheme identifiers will be applied to a creditor and used against payments.
pendingactiveminimum_advance_noticeintegerrequired
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_referencebooleanrequired
Whether a custom reference can be submitted for mandates using this scheme identifier.
currencyenumrequired
The currency of the scheme identifier.
AUDCADDKKEURGBPNZDSEKUSDaddress_line1string | nullrequired
The first line of the scheme identifier's support address.
address_line2string | nullrequired
The second line of the scheme identifier's support address.
address_line3string | nullrequired
The third line of the scheme identifier's support address.
citystring | nullrequired
The city of the scheme identifier's support address.
regionstring | nullrequired
The scheme identifier's support address region, county or department.
postal_codestring | nullrequired
The scheme identifier's support postal code.
country_codestring | nullrequired
emailstring | nullrequired
Scheme identifier's support email address.
phone_numberstring | nullrequired
Scheme identifier's support phone number.
Errors 400401404422500
Bad Request
Unauthorised
Not found
Validation Error
Internal Error
Error Body
errorobjectrequiredGeneric error
6 properties
codeintegerdocumentation_urlstringerrorsarrayrequired
6 properties
reasonstringfieldstringrequest_pointerstringmessagestringrequiredmetadataobjectlinksobjectmessagestringrequiredrequest_idstringrequiredtypestring