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
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_transferlinksobject
1 properties
creditorstring
required ID of the associated creditor.
Response 201
Resource created successfully
scheme_identifiersobject18 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_transferreferencestring
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.
pendingactiveminimum_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.
AUDCADDKKEURGBPNZDSEKUSDaddress_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
Bad Request
Unauthorised
Not found
Validation Error
Internal Error
Error Body
codeintegerdocumentation_urlstringerrorsarray2 properties
reasonstringmessagestringmessagestringrequest_idstringtypestringmetadataobjectlinksobjectList scheme identifiers#
/scheme_identifiersReturns a cursor-paginated list of your scheme identifiers.
Response 200
Successful response
scheme_identifiersarray18 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_transferreferencestring
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.
pendingactiveminimum_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.
AUDCADDKKEURGBPNZDSEKUSDaddress_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.
metaobject2 properties
limitintegercursorsobject
2 properties
beforestring
Cursor pointing to the end of the desired set.
afterstring
Cursor pointing to the start of the desired set.
Errors 400401404422500
Bad Request
Unauthorised
Not found
Validation Error
Internal Error
Error Body
codeintegerdocumentation_urlstringerrorsarray2 properties
reasonstringmessagestringmessagestringrequest_idstringtypestringmetadataobjectlinksobjectGet a single scheme identifier#
/scheme_identifiers/{scheme_identifier_id}Retrieves the details of an existing scheme identifier.
Path Parameters
| Name | Type | Description |
|---|---|---|
scheme_identifier_idrequired | string | The scheme identifier id |
Response 200
Successful response
scheme_identifiersobject18 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_transferreferencestring
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.
pendingactiveminimum_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.
AUDCADDKKEURGBPNZDSEKUSDaddress_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
Bad Request
Unauthorised
Not found
Validation Error
Internal Error
Error Body
codeintegerdocumentation_urlstringerrorsarray2 properties
reasonstringmessagestringmessagestringrequest_idstringtypestringmetadataobjectlinksobject