Creditor

View as Markdown

Each payment taken through the API is linked to a "creditor", to whom the payment is then paid out. In most cases your organisation will have a single "creditor", but the API also supports collecting payments on behalf of others.

Currently, for Anti Money Laundering reasons, any creditors you add must be directly related to your organisation.

Create a creditor#

POST/creditors

Creates a new creditor.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/creditors HTTP/1.1
Content-Type: application/json
{
  "creditors": {
    "name": "Acme",
    "country_code": "GB",
    "creditor_type": "company",
    "bank_reference_prefix": "ACME"
  }
}

@client.creditors.create(
  params: {
    name: "Acme",
    country_code: "GB",
    creditor_type: "company",
    bank_reference_prefix: "ACME",
  }
)

client.creditors.create(params={
  "name": "Acme",
  "country_code": "GB",
  "creditor_type": "company",
  "bank_reference_prefix": "ACME",
})

const creditor = await client.creditors.create({
  name: "Acme",
  country_code: "GB",
  creditor_type: "company",
  bank_reference_prefix: "ACME",
});

$client->creditors()->create([
  'params' => ['name' => 'Acme',
               'country_code' => 'GB',
               'bank_reference_prefix' => 'ACME',
               'creditor_type' => 'company']
]);

import com.gocardless.services.CreditorService.CreditorCreateRequest.CreditorType;

Creditor creditor = client.creditors().create()
  .withName("Acme")
  .withCountryCode("GB")
  .withCreditorType(CreditorType.COMPANY)
  .withBankReferencePrefix("ACME")
  .execute();

creditorCreateParams := gocardless.CreditorCreateParams{
  Name:                "Acme",
  CountryCode:         "GB",
  CreditorType:        "company",
  BankReferencePrefix: "ACME",
}

creditor, err := client.Creditors.Create(ctx, creditorCreateParams)

var creditorRequest = new GoCardless.Services.CreditorCreateRequest()
{
    Name = "Acme",
    CountryCode = "GB",
    CreditorType = GoCardless.Services.CreditorCreateRequest.CreditorCreditorType.Company,
    BankReferencePrefix = "ACME",
};

var creditorResponse = await client.Creditors.CreateAsync(creditorRequest);
GoCardless.Resources.Creditor creditor = creditorResponse.Creditor;

Responsehttp

HTTP/1.1 201 Created
Location: /creditors/CR123
Content-Type: application/json
{
  "creditors": {
    "id": "CR123",
    "created_at": "2017-02-16T12:34:56.000Z",
    "name": "Acme",
    "address_line1": null,
    "address_line2": null,
    "address_line3": null,
    "city": null,
    "region": null,
    "postal_code": null,
    "country_code": "GB",
    "creditor_type": "company",
    "logo_url": null,
    "scheme_identifiers": [],
    "verification_status": "successful",
    "can_create_refunds": false,
    "fx_payout_currency": null,
    "mandate_imports_enabled": false,
    "custom_payment_pages_enabled": true,
    "merchant_responsible_for_notifications": true,
    "bank_reference_prefix": "ACME",
    "links": {}
  }
}

Request Body

creditorsobject

5 properties

namestringrequired

The creditor's trading name.

country_codestring | nullrequired

ISO 3166-1 alpha-2 code.

creditor_typestring | nullrequired

The type of business of the creditor. Currently, individual, company, charity, partnership, and trust are supported.

companyindividualcharitypartnershiptrust

bank_reference_prefixstring

Prefix for the bank reference of payouts sent to this creditor. For instance, if the creditor's bank_reference_prefix was ACME, the bank reference of a payout sent to that creditor could be ACME-8G7Q8.

This prefix is also used for refunds in EUR and GBP.

linksobject

0 properties

Response 201

Resource created successfully

creditorsobject

21 properties

idstring

Unique identifier, beginning with "CR".

created_atstring

Fixed timestamp, recording when this resource was created.

namestring

The creditor's trading name.

address_line1string | null

The first line of the creditor's address.

address_line2string | null

The second line of the creditor's address.

address_line3string | null

The third line of the creditor's address.

citystring | null

The city of the creditor's address.

regionstring | null

The creditor's address region, county or department.

postal_codestring | null

The creditor's postal code.

country_codestring | null

ISO 3166-1 alpha-2 code.

can_create_refundsboolean

Boolean indicating whether the creditor is permitted to create refunds.

bank_reference_prefixstring

This prefix is also used for refunds in EUR and GBP.

linksobject

8 properties

default_aud_payout_accountstring | null

ID of the bank account which is set up to receive payouts in AUD.

default_gbp_payout_accountstring | null

ID of the bank account which is set up to receive payouts in GBP.

default_eur_payout_accountstring | null

ID of the bank account which is set up to receive payouts in EUR.

default_sek_payout_accountstring | null

ID of the bank account which is set up to receive payouts in SEK.

default_dkk_payout_accountstring | null

ID of the bank account which is set up to receive payouts in DKK.

default_nzd_payout_accountstring | null

ID of the bank account which is set up to receive payouts in NZD.

default_cad_payout_accountstring | null

ID of the bank account which is set up to receive payouts in CAD.

default_usd_payout_accountstring | null

ID of the bank account which is set up to receive payouts in USD.

scheme_identifiersarray

An array of the scheme identifiers this creditor can create mandates against.

The support address, phone_number and email fields are for customers to contact the merchant for support purposes. They must be displayed on the payment page, please see our compliance requirements for more details.

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 | null

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.

address_line1string | null

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

address_line2string | null

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

address_line3string | null

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

citystring | null

The city of the scheme identifier's support address.

regionstring | null

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

postal_codestring

The scheme identifier's support postal code.

country_codestring

ISO 3166-1 alpha-2 code.

emailstring | null

Scheme identifier's support email address.

phone_numberstring | null

Scheme identifier's support phone number.

currencystring

The currency of the scheme identifier.

AUDCADDKKEURGBPNZDSEKUSD

can_specify_mandate_referenceboolean

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

logo_urlstring | null

URL for the creditor's logo, which may be shown on their payment pages.

verification_statusstring

The creditor's verification status, indicating whether they can yet receive payouts. For more details on handling verification as a partner, see our "Helping your users get verified" guide. One of:

successful: The creditor's account is fully verified, and they can receive payouts. Once a creditor has been successfully verified, they may in the future require further verification - for example, if they change their payout bank account, we will have to check that they own the new bank account before they can receive payouts again.
in_review: The creditor has provided all of the information currently requested, and it is awaiting review by GoCardless before they can be verified and receive payouts.
action_required: The creditor needs to provide further information to verify their account so they can receive payouts, and should visit the verification flow.

successfulin_reviewaction_required

merchant_responsible_for_notificationsboolean

Boolean value indicating whether the organisation is responsible for sending all customer notifications (note this is separate from the functionality described here). If you are a partner app, and this value is true, you should not send notifications on behalf of this organisation.

mandate_imports_enabledboolean

Boolean value indicating whether creditor has the Mandate Imports functionality enabled.

custom_payment_pages_enabledboolean

Boolean value indicating whether creditor has the Custom Payment Pages functionality enabled.

fx_payout_currencystring | null

ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. Present only if payouts will be (or were) made via foreign exchange.

AUDCADDKKEURGBPNZDSEKUSD

creditor_typestring | null

The type of business of the creditor. Currently, individual, company, charity, partnership, and trust are supported.

companyindividualcharitypartnershiptrust

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

errorobjectrequired

Generic error

6 properties

codeinteger

documentation_urlstring

errorsarrayrequired

6 properties

reasonstring

fieldstring

request_pointerstring

messagestringrequired

metadataobject

linksobject

messagestringrequired

request_idstringrequired

typestring

List creditors#

GET/creditors

Returns a cursor-paginated list of your creditors.

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.
`created_at`	object	4 properties `gt`string Limit to records created after the specified date-time. `lt`string Limit to records created before the specified date-time. `gte`string Limit to records created on or after the specified date-time. `lte`string Limit to records created on or before the specified date-time.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/creditors HTTP/1.1

@client.creditors.list

@client.creditors.list(params: { limit: 2 })

client.creditors.list().records

const creditors = await client.creditors.list();

// List the first three creditors.
const limitedCreditors = await client.creditors.list({ limit: 3 });

$client->creditors()->list();

$client->creditors()->list([
  'params' => ['created_at[gt]' => '2014-05-08T17:01:06.000Z']
]);

for (Creditor creditor : client.creditors().all().execute()) {
  System.out.println(creditor.getId());
}

creditorListParams := gocardless.CreditorListParams{
  Limit: 3,
}

// List the first three creditors.
creditorListResult, err := client.Creditors.List(ctx, creditorListParams)
for _, creditor := range creditorListResult.Creditors {
    fmt.Println(creditor.Name)
}

var creditorListResponse = client.Creditors.All();
foreach (GoCardless.Resources.Creditor creditor in creditorListResponse)
{
    Console.WriteLine(creditor.Name);
}

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "creditors":[{
    "id": "CR123",
    "created_at": "2017-02-16T12:34:56.000Z",
    "name": "Acme",
    "address_line1": null,
    "address_line2": null,
    "address_line3": null,
    "city": null,
    "region": null,
    "postal_code": null,
    "country_code": "GB",
    "creditor_type": "company",
    "logo_url": null,
    "scheme_identifiers": [],
    "verification_status": "successful",
    "can_create_refunds": false,
    "fx_payout_currency": null,
    "mandate_imports_enabled": false,
    "custom_payment_pages_enabled": true,
    "merchant_responsible_for_notifications": true,
    "bank_reference_prefix": "ACME",
    "links": {}
  }]
}

Response 200

Successful response

creditorsarray

21 properties

idstring

Unique identifier, beginning with "CR".

created_atstring

Fixed timestamp, recording when this resource was created.

namestring

The creditor's trading name.

address_line1string | null

The first line of the creditor's address.

address_line2string | null

The second line of the creditor's address.

address_line3string | null

The third line of the creditor's address.

citystring | null

The city of the creditor's address.

regionstring | null

The creditor's address region, county or department.

postal_codestring | null

The creditor's postal code.

country_codestring | null

ISO 3166-1 alpha-2 code.

can_create_refundsboolean

Boolean indicating whether the creditor is permitted to create refunds.

bank_reference_prefixstring

This prefix is also used for refunds in EUR and GBP.

linksobject

8 properties

default_aud_payout_accountstring | null

ID of the bank account which is set up to receive payouts in AUD.

default_gbp_payout_accountstring | null

ID of the bank account which is set up to receive payouts in GBP.

default_eur_payout_accountstring | null

ID of the bank account which is set up to receive payouts in EUR.

default_sek_payout_accountstring | null

ID of the bank account which is set up to receive payouts in SEK.

default_dkk_payout_accountstring | null

ID of the bank account which is set up to receive payouts in DKK.

default_nzd_payout_accountstring | null

ID of the bank account which is set up to receive payouts in NZD.

default_cad_payout_accountstring | null

ID of the bank account which is set up to receive payouts in CAD.

default_usd_payout_accountstring | null

ID of the bank account which is set up to receive payouts in USD.

scheme_identifiersarray

An array of the scheme identifiers this creditor can create mandates against.

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 | null

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.

address_line1string | null

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

address_line2string | null

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

address_line3string | null

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

citystring | null

The city of the scheme identifier's support address.

regionstring | null

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

postal_codestring

The scheme identifier's support postal code.

country_codestring

ISO 3166-1 alpha-2 code.

emailstring | null

Scheme identifier's support email address.

phone_numberstring | null

Scheme identifier's support phone number.

currencystring

The currency of the scheme identifier.

AUDCADDKKEURGBPNZDSEKUSD

can_specify_mandate_referenceboolean

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

logo_urlstring | null

URL for the creditor's logo, which may be shown on their payment pages.

verification_statusstring

The creditor's verification status, indicating whether they can yet receive payouts. For more details on handling verification as a partner, see our "Helping your users get verified" guide. One of:

successful: The creditor's account is fully verified, and they can receive payouts. Once a creditor has been successfully verified, they may in the future require further verification - for example, if they change their payout bank account, we will have to check that they own the new bank account before they can receive payouts again.
in_review: The creditor has provided all of the information currently requested, and it is awaiting review by GoCardless before they can be verified and receive payouts.
action_required: The creditor needs to provide further information to verify their account so they can receive payouts, and should visit the verification flow.

successfulin_reviewaction_required

merchant_responsible_for_notificationsboolean

mandate_imports_enabledboolean

Boolean value indicating whether creditor has the Mandate Imports functionality enabled.

custom_payment_pages_enabledboolean

Boolean value indicating whether creditor has the Custom Payment Pages functionality enabled.

fx_payout_currencystring | null

AUDCADDKKEURGBPNZDSEKUSD

creditor_typestring | null

The type of business of the creditor. Currently, individual, company, charity, partnership, and trust are supported.

companyindividualcharitypartnershiptrust

metaobject

2 properties

limitintegerrequired

cursorsobjectrequired

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

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

errorobjectrequired

Generic error

6 properties

codeinteger

documentation_urlstring

errorsarrayrequired

6 properties

reasonstring

fieldstring

request_pointerstring

messagestringrequired

metadataobject

linksobject

messagestringrequired

request_idstringrequired

typestring

Get a single creditor#

GET/creditors/{creditor_id}

Retrieves the details of an existing creditor.

Path Parameters

Name	Type	Description
`creditor_id`	stringrequired	The creditor id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/creditors/CR123 HTTP/1.1

@client.creditors.get("CR123")

client.creditors.get("CR123")

const creditor = await client.creditors.find("CR123");

$client->creditors()->get('CR123');

Creditor creditor = client.creditors().get("CR123").execute();

creditor, err := client.Creditors.Get(ctx, "CR123", gocardless.CreditorGetParams{})

var creditorResponse = await client.Creditors.GetAsync("CR0123");
GoCardless.Resources.Creditor creditor = creditorResponse.Creditor;

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "creditors": {
    "id": "CR123",
    "created_at": "2017-02-16T12:34:56.000Z",
    "name": "Acme",
    "address_line1": null,
    "address_line2": null,
    "address_line3": null,
    "city": null,
    "region": null,
    "postal_code": null,
    "country_code": "GB",
    "creditor_type": "company",
    "logo_url": null,
    "scheme_identifiers": [],
    "verification_status": "successful",
    "can_create_refunds": false,
    "fx_payout_currency": null,
    "mandate_imports_enabled": false,
    "custom_payment_pages_enabled": true,
    "merchant_responsible_for_notifications": true,
    "bank_reference_prefix": "ACME",
    "links": {}
  }
}

Response 200

Successful response

creditorsobject

21 properties

idstring

Unique identifier, beginning with "CR".

created_atstring

Fixed timestamp, recording when this resource was created.

namestring

The creditor's trading name.

address_line1string | null

The first line of the creditor's address.

address_line2string | null

The second line of the creditor's address.

address_line3string | null

The third line of the creditor's address.

citystring | null

The city of the creditor's address.

regionstring | null

The creditor's address region, county or department.

postal_codestring | null

The creditor's postal code.

country_codestring | null

ISO 3166-1 alpha-2 code.

can_create_refundsboolean

Boolean indicating whether the creditor is permitted to create refunds.

bank_reference_prefixstring

This prefix is also used for refunds in EUR and GBP.

linksobject

8 properties

default_aud_payout_accountstring | null

ID of the bank account which is set up to receive payouts in AUD.

default_gbp_payout_accountstring | null

ID of the bank account which is set up to receive payouts in GBP.

default_eur_payout_accountstring | null

ID of the bank account which is set up to receive payouts in EUR.

default_sek_payout_accountstring | null

ID of the bank account which is set up to receive payouts in SEK.

default_dkk_payout_accountstring | null

ID of the bank account which is set up to receive payouts in DKK.

default_nzd_payout_accountstring | null

ID of the bank account which is set up to receive payouts in NZD.

default_cad_payout_accountstring | null

ID of the bank account which is set up to receive payouts in CAD.

default_usd_payout_accountstring | null

ID of the bank account which is set up to receive payouts in USD.

scheme_identifiersarray

An array of the scheme identifiers this creditor can create mandates against.

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 | null

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.

address_line1string | null

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

address_line2string | null

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

address_line3string | null

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

citystring | null

The city of the scheme identifier's support address.

regionstring | null

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

postal_codestring

The scheme identifier's support postal code.

country_codestring

ISO 3166-1 alpha-2 code.

emailstring | null

Scheme identifier's support email address.

phone_numberstring | null

Scheme identifier's support phone number.

currencystring

The currency of the scheme identifier.

AUDCADDKKEURGBPNZDSEKUSD

can_specify_mandate_referenceboolean

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

logo_urlstring | null

URL for the creditor's logo, which may be shown on their payment pages.

verification_statusstring

The creditor's verification status, indicating whether they can yet receive payouts. For more details on handling verification as a partner, see our "Helping your users get verified" guide. One of:

successful: The creditor's account is fully verified, and they can receive payouts. Once a creditor has been successfully verified, they may in the future require further verification - for example, if they change their payout bank account, we will have to check that they own the new bank account before they can receive payouts again.
in_review: The creditor has provided all of the information currently requested, and it is awaiting review by GoCardless before they can be verified and receive payouts.
action_required: The creditor needs to provide further information to verify their account so they can receive payouts, and should visit the verification flow.

successfulin_reviewaction_required

merchant_responsible_for_notificationsboolean

mandate_imports_enabledboolean

Boolean value indicating whether creditor has the Mandate Imports functionality enabled.

custom_payment_pages_enabledboolean

Boolean value indicating whether creditor has the Custom Payment Pages functionality enabled.

fx_payout_currencystring | null

AUDCADDKKEURGBPNZDSEKUSD

creditor_typestring | null

The type of business of the creditor. Currently, individual, company, charity, partnership, and trust are supported.

companyindividualcharitypartnershiptrust

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

errorobjectrequired

Generic error

6 properties

codeinteger

documentation_urlstring

errorsarrayrequired

6 properties

reasonstring

fieldstring

request_pointerstring

messagestringrequired

metadataobject

linksobject

messagestringrequired

request_idstringrequired

typestring

Update a creditor#

PUT/creditors/{creditor_id}

Updates a creditor object. Supports all of the fields supported when creating a creditor.

Path Parameters

Name	Type	Description
`creditor_id`	stringrequired	The creditor id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

PUT https://api.gocardless.com/creditors/CR123 HTTP/1.1
Content-Type: application/json
{
  "creditors": {
    "links": {
      "default_gbp_payout_account": "BA789"
    }
  }
}

@client.creditors.update(
  "CR123",
  params: {
    links: { default_gbp_payout_account: "BA789" }
  }
)

client.creditors.update("CR123", params={
  "links": {
    "default_gbp_payout_account": "BA789"
  }
})

const creditor = await client.creditors.update(
  "CR123",
  {
    links: {
      default_gbp_payout_account: "BA789"
    }
  }
);

$client->creditors()->update('CR123', [
  'params' => ['links' => ['default_gbp_payout_account' => 'BA789']]
]);

client.creditors().update("CR123")
  .withLinksDefaultGbpPayoutAccount("BA789")
  .execute();

creditorUpdateParams := gocardless.CreditorUpdateParams{
  Links: &gocardless.CreditorUpdateParamsLinks{
    DefaultGbpPayoutAccount: "BA789",
  },
}

creditor, err := client.Creditors.Update(ctx, "CR123", creditorUpdateParams)

var creditorRequest = new GoCardless.Services.CreditorUpdateRequest()
{
    Links = new GoCardless.Services.CreditorUpdateRequest.CreditorLinks()
    {
        DefaultGbpPayoutAccount = "BA789"
    }
};

var creditorResponse = await client.Creditors.UpdateAsync("CR0123", creditorRequest);

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "creditors": {
    "id": "CR123",
    "created_at": "2017-02-16T12:34:56.000Z",
    "name": "Acme",
    "address_line1": null,
    "address_line2": null,
    "address_line3": null,
    "city": null,
    "region": null,
    "postal_code": null,
    "country_code": "GB",
    "creditor_type": "company",
    "logo_url": null,
    "scheme_identifiers": [],
    "verification_status": "successful",
    "can_create_refunds": false,
    "fx_payout_currency": null,
    "mandate_imports_enabled": false,
    "custom_payment_pages_enabled": true,
    "merchant_responsible_for_notifications": true,
    "bank_reference_prefix": "ACME",
    "links": {
      "default_gbp_payout_account": "BA789"
    }
  }
}

Request Body

creditorsobject

10 properties

namestring

The creditor's trading name.

address_line1string | null

The first line of the creditor's address.

address_line2string | null

The second line of the creditor's address.

address_line3string | null

The third line of the creditor's address.

citystring | null

The city of the creditor's address.

regionstring | null

The creditor's address region, county or department.

postal_codestring | null

The creditor's postal code.

country_codestring | null

ISO 3166-1 alpha-2 code.

bank_reference_prefixstring

This prefix is also used for refunds in EUR and GBP.

linksobject

8 properties

default_aud_payout_accountstring | null

ID of the bank account which is set up to receive payouts in AUD.

default_gbp_payout_accountstring | null

ID of the bank account which is set up to receive payouts in GBP.

default_eur_payout_accountstring | null

ID of the bank account which is set up to receive payouts in EUR.

default_sek_payout_accountstring | null

ID of the bank account which is set up to receive payouts in SEK.

default_dkk_payout_accountstring | null

ID of the bank account which is set up to receive payouts in DKK.

default_nzd_payout_accountstring | null

ID of the bank account which is set up to receive payouts in NZD.

default_cad_payout_accountstring | null

ID of the bank account which is set up to receive payouts in CAD.

default_usd_payout_accountstring | null

ID of the bank account which is set up to receive payouts in USD.

Response 200

Successful response

creditorsobject

21 properties

idstring

Unique identifier, beginning with "CR".

created_atstring

Fixed timestamp, recording when this resource was created.

namestring

The creditor's trading name.

address_line1string | null

The first line of the creditor's address.

address_line2string | null

The second line of the creditor's address.

address_line3string | null

The third line of the creditor's address.

citystring | null

The city of the creditor's address.

regionstring | null

The creditor's address region, county or department.

postal_codestring | null

The creditor's postal code.

country_codestring | null

ISO 3166-1 alpha-2 code.

can_create_refundsboolean

Boolean indicating whether the creditor is permitted to create refunds.

bank_reference_prefixstring

This prefix is also used for refunds in EUR and GBP.

linksobject

8 properties

default_aud_payout_accountstring | null

ID of the bank account which is set up to receive payouts in AUD.

default_gbp_payout_accountstring | null

ID of the bank account which is set up to receive payouts in GBP.

default_eur_payout_accountstring | null

ID of the bank account which is set up to receive payouts in EUR.

default_sek_payout_accountstring | null

ID of the bank account which is set up to receive payouts in SEK.

default_dkk_payout_accountstring | null

ID of the bank account which is set up to receive payouts in DKK.

default_nzd_payout_accountstring | null

ID of the bank account which is set up to receive payouts in NZD.

default_cad_payout_accountstring | null

ID of the bank account which is set up to receive payouts in CAD.

default_usd_payout_accountstring | null

ID of the bank account which is set up to receive payouts in USD.

scheme_identifiersarray

An array of the scheme identifiers this creditor can create mandates against.

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 | null

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.

address_line1string | null

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

address_line2string | null

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

address_line3string | null

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

citystring | null

The city of the scheme identifier's support address.

regionstring | null

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

postal_codestring

The scheme identifier's support postal code.

country_codestring

ISO 3166-1 alpha-2 code.

emailstring | null

Scheme identifier's support email address.

phone_numberstring | null

Scheme identifier's support phone number.

currencystring

The currency of the scheme identifier.

AUDCADDKKEURGBPNZDSEKUSD

can_specify_mandate_referenceboolean

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

logo_urlstring | null

URL for the creditor's logo, which may be shown on their payment pages.

verification_statusstring

The creditor's verification status, indicating whether they can yet receive payouts. For more details on handling verification as a partner, see our "Helping your users get verified" guide. One of:

successful: The creditor's account is fully verified, and they can receive payouts. Once a creditor has been successfully verified, they may in the future require further verification - for example, if they change their payout bank account, we will have to check that they own the new bank account before they can receive payouts again.
in_review: The creditor has provided all of the information currently requested, and it is awaiting review by GoCardless before they can be verified and receive payouts.
action_required: The creditor needs to provide further information to verify their account so they can receive payouts, and should visit the verification flow.

successfulin_reviewaction_required

merchant_responsible_for_notificationsboolean

mandate_imports_enabledboolean

Boolean value indicating whether creditor has the Mandate Imports functionality enabled.

custom_payment_pages_enabledboolean

Boolean value indicating whether creditor has the Custom Payment Pages functionality enabled.

fx_payout_currencystring | null

AUDCADDKKEURGBPNZDSEKUSD

creditor_typestring | null

The type of business of the creditor. Currently, individual, company, charity, partnership, and trust are supported.

companyindividualcharitypartnershiptrust

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

errorobjectrequired

Generic error

6 properties

codeinteger

documentation_urlstring

errorsarrayrequired

6 properties

reasonstring

fieldstring

request_pointerstring

messagestringrequired

metadataobject

linksobject

messagestringrequired

request_idstringrequired

typestring