GoCardlessDeveloper Docs
Create a sandbox account

Block

View as Markdown

Blocks are created to prevent certain customer details from being used when creating mandates.

The details used to create blocks can be exact matches, like a bank account or an email, or a more generic match such as an email domain or bank name. Please be careful when creating blocks for more generic matches as this may block legitimate payers from using your service.

New block types may be added over time.

A block is in essence a simple rule that is used to match against details in a newly created mandate. If there is a successful match then the mandate is transitioned to a "blocked" state.

Please note:

  • Payments and subscriptions cannot be created against a mandate in blocked state.
  • A mandate can never be transitioned out of the blocked state.

The one exception to this is when blocking a 'bank_name'. This block will prevent bank accounts from being created for banks that match the given name. To ensure we match bank names correctly an existing bank account must be used when creating this block. Please be aware that we cannot always match a bank account to a given bank name.

Create a block#

POST/blocks

Creates a new Block of a given type. By default it will be active.

POST https://api.gocardless.com/blocks HTTP/1.1
Content-Type: application/json
{
  "blocks": {
    "block_type": "email",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "example@example.com"
  }
}
block = @client.blocks.create(
  params: {
    block_type: "email",
    reason_type: "no_intent_to_pay",
    resource_reference: "example@example.com"
  }
)
block = client.blocks.create(
  params={
    "block_type": "email",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "example@example.com"
  }
)
const block = await client.blocks.create({
  block_type: Types.BlockBlockType.Email,
  resource_reference: 'CU123',
  reason_type: Types.BlockReasonType.NoIntentToPay,
})
$block = $client->blocks()->create([
  "params" => [
      "block_type" => "email",
      "reason_type" => "no_intent_to_pay",
      "resource_reference" => "example@example.com",
  ]
]);
Block block = client.blocks().create()
  .withBlockType("email")
  .withReasonType("no_intent_to_pay")
  .withResourceReference("example@example.com")
  .execute();
blockCreateParams := gocardless.BlockCreateParams{
  BlockType:         "email",
  ReasonType:        "no_intent_to_pay",
  ResourceReference: "example@example.com",
}

block, err := client.Blocks.Create(ctx, blockCreateParams)
var resp = await client.Blocks.CreateAsync(
  new GoCardless.Services.BlockCreateRequest()
  {
      BlockType = "email",
      ReasonType = "no_intent_to_pay",
      ResourceReference = "example@example.com"
  }
);
GoCardless.Resources.Block block = resp.Block;
Responsehttp
HTTP/1.1 201 Created
Location: /block/BLC123
Content-Type: application/json
{
  "blocks": {
    "id": "BLC123",
    "block_type": "email",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "example@example.com",
    "active": true,
    "created_at": "2021-03-25T17:26:28.305Z",
    "updated_at": "2021-03-25T17:26:28.305Z"
  }
}

POST https://api.gocardless.com/blocks HTTP/1.1
Content-Type: application/json
{
  "blocks": {
    "block_type": "bank_account",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "BA123"
  }
}

HTTP/1.1 201 Created
Location: /block/BLC456
Content-Type: application/json
{
  "blocks": {
    "id": "BLC456",
    "block_type": "bank_account",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "BA123",
    "active": true,
    "created_at": "2021-03-25T17:26:28.305Z",
    "updated_at": "2021-03-25T17:26:28.305Z"
  }
}
Request Body
blocksobject
5 properties
block_typestring

Type of entity we will seek to match against when blocking the mandate. This can currently be one of 'email', 'email_domain', 'bank_account', or 'bank_name'.

emailemail_domainbank_accountbank_name
reason_typestring

The reason you wish to block this payer, can currently be one of 'identity_fraud', 'no_intent_to_pay', 'unfair_chargeback'. If the reason isn't captured by one of the above then 'other' can be selected but you must provide a reason description.

identity_fraudno_intent_to_payunfair_chargebackother
reason_descriptionstring

This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.

resource_referencestring

This field is a reference to the value you wish to block. This may be the raw value (in the case of emails or email domains) or the ID of the resource (in the case of bank accounts and bank names). This means in order to block a specific bank account (even if you wish to block generically by name) it must already have been created as a resource.

activeboolean

Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.

Response 201

Resource created successfully

blocksobject
8 properties
idstring

Unique identifier, beginning with "BLC".

block_typestring

Type of entity we will seek to match against when blocking the mandate. This can currently be one of 'email', 'email_domain', 'bank_account', or 'bank_name'.

emailemail_domainbank_accountbank_name
reason_typestring

The reason you wish to block this payer, can currently be one of 'identity_fraud', 'no_intent_to_pay', 'unfair_chargeback'. If the reason isn't captured by one of the above then 'other' can be selected but you must provide a reason description.

identity_fraudno_intent_to_payunfair_chargebackother
reason_descriptionstring

This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.

resource_referencestring

This field is a reference to the value you wish to block. This may be the raw value (in the case of emails or email domains) or the ID of the resource (in the case of bank accounts and bank names). This means in order to block a specific bank account (even if you wish to block generically by name) it must already have been created as a resource.

activeboolean

Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.

created_atstring

Fixed timestamp, recording when this resource was created.

updated_atstring

Fixed timestamp, recording when this resource was updated.

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 multiple blocks#

GET/blocks

Returns a cursor-paginated list of your blocks.

GET https://api.gocardless.com/blocks HTTP/1.1
@client.blocks.all.each do |block|
  puts block.id
  puts block.block_type
end
for block in client.blocks.all():
  print(block.id)
  print(block.block_type)
for await (const block of client.blocks.all({})) {
  console.log(block.id);
  console.log(block.block_type);
}
foreach ($client->blocks()->all() as $record) {
  echo $record->id;
  echo $record->block_type;
}
for (Block block : client.blocks().all().execute()) {
    System.out.println(block.getId());
    System.out.println(block.getBlockType());
}
blockListParams := gocardless.BlockListParams{}
blockListResult, err := client.Blocks.List(ctx, blockListParams)
for _, block := range blockListResult.Blocks {
    fmt.Println(block.Id)
}
foreach (GoCardless.Resources.Block block in client.Blocks.All())
{
    Console.WriteLine(block.Id);
}
Responsehttp
HTTP/1.1 200 OK
Location: /blocks
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "blocks": [
    {
      "id": "BLC123",
      "block_type": "email",
      "reason_type": "no_intent_to_pay",
      "resource_reference": "example@example.com",
      "active": true,
      "created_at": "2021-03-25T17:26:28.305Z",
      "updated_at": "2021-03-25T17:26:28.305Z"
    },
    {
      "id": "BLC456",
      "block_type": "email_domain",
      "reason_type": "identity_fraud",
      "resource_reference": "example.com",
      "active": true,
      "created_at": "2021-03-25T17:26:28.305Z",
      "updated_at": "2021-03-25T17:26:28.305Z"
    }
  ]
}
Response 200

Successful response

blocksarray
8 properties
idstring

Unique identifier, beginning with "BLC".

block_typestring

Type of entity we will seek to match against when blocking the mandate. This can currently be one of 'email', 'email_domain', 'bank_account', or 'bank_name'.

emailemail_domainbank_accountbank_name
reason_typestring

The reason you wish to block this payer, can currently be one of 'identity_fraud', 'no_intent_to_pay', 'unfair_chargeback'. If the reason isn't captured by one of the above then 'other' can be selected but you must provide a reason description.

identity_fraudno_intent_to_payunfair_chargebackother
reason_descriptionstring

This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.

resource_referencestring

This field is a reference to the value you wish to block. This may be the raw value (in the case of emails or email domains) or the ID of the resource (in the case of bank accounts and bank names). This means in order to block a specific bank account (even if you wish to block generically by name) it must already have been created as a resource.

activeboolean

Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.

created_atstring

Fixed timestamp, recording when this resource was created.

updated_atstring

Fixed timestamp, recording when this resource was updated.

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 block#

GET/blocks/{block_id}

Retrieves the details of an existing block.

Path Parameters

NameTypeDescription
block_idrequiredstring

The block id

GET https://api.gocardless.com/blocks/BLC456 HTTP/1.1
block = @client.blocks.get("BLC456")
block = client.blocks.get("BLC456")
const block = await client.blocks.find("BLC456");
$block = $client->blocks()->get("BLC456");
Block block = client.blocks().get("BLC456").execute();
block, err := client.Blocks.Get(ctx, "BLC456")
var resp = await client.Blocks.GetAsync("BLC456");
GoCardless.Resources.Block block = resp.Block;
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "blocks": {
    "id": "BLC456",
    "block_type": "email",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "example@example.com",
    "active": true,
    "created_at": "2021-03-25T17:26:28.305Z",
    "updated_at": "2021-03-25T17:26:28.305Z"
  }
}
Response 200

Successful response

blocksobject
8 properties
idstring

Unique identifier, beginning with "BLC".

block_typestring

Type of entity we will seek to match against when blocking the mandate. This can currently be one of 'email', 'email_domain', 'bank_account', or 'bank_name'.

emailemail_domainbank_accountbank_name
reason_typestring

The reason you wish to block this payer, can currently be one of 'identity_fraud', 'no_intent_to_pay', 'unfair_chargeback'. If the reason isn't captured by one of the above then 'other' can be selected but you must provide a reason description.

identity_fraudno_intent_to_payunfair_chargebackother
reason_descriptionstring

This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.

resource_referencestring

This field is a reference to the value you wish to block. This may be the raw value (in the case of emails or email domains) or the ID of the resource (in the case of bank accounts and bank names). This means in order to block a specific bank account (even if you wish to block generically by name) it must already have been created as a resource.

activeboolean

Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.

created_atstring

Fixed timestamp, recording when this resource was created.

updated_atstring

Fixed timestamp, recording when this resource was updated.

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

Disable a block#

POST/blocks/{block_id}/actions/disable

Disables a block so that it no longer will prevent mandate creation.

Path Parameters

NameTypeDescription
block_idrequiredstring

The block id

POST https://api.gocardless.com/blocks/BLC123/actions/disable HTTP/1.1
block = @client.blocks.disable("BLC123")
block = client.blocks.disable("BLC123")
const block = await client.blocks.disable("BLC456");
$block = $client->blocks()->disable("BLC123");
Block block = client.blocks().disable("BLC123").execute();
block, err := client.Blocks.Disable(ctx, "BLC123")
var resp = await client.Blocks.DisableAsync("BLC123");
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "blocks": {
    "id": "BLC123",
    "block_type": "bank_account",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "BA123",
    "active": false,
    "created_at": "2021-03-25T17:26:28.305Z",
    "updated_at": "2021-03-25T19:26:28.305Z"
  }
}

POST https://api.gocardless.com/blocks/BLC123/actions/disable HTTP/1.1
HTTP/1.1 409 Conflict

POST https://api.gocardless.com/blocks/MISSING_BLOCK_ID/actions/disable HTTP/1.1
HTTP/1.1 404 NotFound
Response 200

Action completed successfully

blocksobject
8 properties
idstring

Unique identifier, beginning with "BLC".

block_typestring

Type of entity we will seek to match against when blocking the mandate. This can currently be one of 'email', 'email_domain', 'bank_account', or 'bank_name'.

emailemail_domainbank_accountbank_name
reason_typestring

The reason you wish to block this payer, can currently be one of 'identity_fraud', 'no_intent_to_pay', 'unfair_chargeback'. If the reason isn't captured by one of the above then 'other' can be selected but you must provide a reason description.

identity_fraudno_intent_to_payunfair_chargebackother
reason_descriptionstring

This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.

resource_referencestring

This field is a reference to the value you wish to block. This may be the raw value (in the case of emails or email domains) or the ID of the resource (in the case of bank accounts and bank names). This means in order to block a specific bank account (even if you wish to block generically by name) it must already have been created as a resource.

activeboolean

Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.

created_atstring

Fixed timestamp, recording when this resource was created.

updated_atstring

Fixed timestamp, recording when this resource was updated.

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

Enable a block#

POST/blocks/{block_id}/actions/enable

Enables a previously disabled block so that it will prevent mandate creation

Path Parameters

NameTypeDescription
block_idrequiredstring

The block id

POST https://api.gocardless.com/blocks/BLC123/actions/enable HTTP/1.1
block = @client.blocks.enable("BLC123")
block = client.blocks.enable("BLC123")
const block = await client.blocks.enable("BLC456");
$block = $client->blocks()->enable("BLC123");
Block block = client.blocks().enable("BLC123").execute();
block, err := client.Blocks.Enable(ctx, "BLC123")
var resp = await client.Blocks.EnableAsync("BLC123");
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "blocks": {
    "id": "BLC123",
    "block_type": "bank_account",
    "reason_type": "no_intent_to_pay",
    "resource_reference": "BA123",
    "active": true,
    "created_at": "2021-03-25T17:26:28.305Z",
    "updated_at": "2021-03-25T19:26:28.305Z"
  }
}

POST https://api.gocardless.com/blocks/BLC123/actions/enable HTTP/1.1
HTTP/1.1 409 Conflict

POST https://api.gocardless.com/blocks/MISSING_BLOCK_ID/actions/enable HTTP/1.1
HTTP/1.1 404 NotFound
Response 200

Action completed successfully

blocksobject
8 properties
idstring

Unique identifier, beginning with "BLC".

block_typestring

Type of entity we will seek to match against when blocking the mandate. This can currently be one of 'email', 'email_domain', 'bank_account', or 'bank_name'.

emailemail_domainbank_accountbank_name
reason_typestring

The reason you wish to block this payer, can currently be one of 'identity_fraud', 'no_intent_to_pay', 'unfair_chargeback'. If the reason isn't captured by one of the above then 'other' can be selected but you must provide a reason description.

identity_fraudno_intent_to_payunfair_chargebackother
reason_descriptionstring

This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.

resource_referencestring

This field is a reference to the value you wish to block. This may be the raw value (in the case of emails or email domains) or the ID of the resource (in the case of bank accounts and bank names). This means in order to block a specific bank account (even if you wish to block generically by name) it must already have been created as a resource.

activeboolean

Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.

created_atstring

Fixed timestamp, recording when this resource was created.

updated_atstring

Fixed timestamp, recording when this resource was updated.

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

Create blocks by reference#

POST/blocks/block_by_ref

Creates new blocks for a given reference. By default blocks will be active. Returns 201 if at least one block was created. Returns 200 if there were no new blocks created.

POST https://api.gocardless.com/blocks/block_by_ref HTTP/1.1
Content-Type: application/json
{
  "blocks": {
    "reference_type": "customer",
    "reference_value": "CU123",
    "reason_type": "no_intent_to_pay"
  }
}
resp = @client.blocks.block_by_ref(
  params: {
    reference_type: "customer",
    reference_value: "CU123",
    reason_type: "no_intent_to_pay",
  }
)
blocks = resp.records
response = client.blocks.block_by_ref(
  params={
    "reference_type": "customer",
    "reference_value": "CU123",
    "reason_type": "no_intent_to_pay"
  }
)
blocks = response.records
const response = await client.blocks.block_by_ref(
  {
    reference_type: Types.BlockReferenceType.Customer,
    reference_value: 'CU123',
    reason_type: Types.BlockReasonType.NoIntentToPay
  }
);
const blocks = response.blocks;
$block = $client->blocks()->blockByRef([
  "params" => [
      "reference_type" => "customer",
      "reference_value" => "CU123",
      "reason_type" => "no_intent_to_pay",
  ]
]);
for (Block block : client.blocks().blockByRef()
        .withReferenceType("customer")
        .withReferenceValue("CU123")
        .withReasonType("no_intent_to_pay")
        .execute()) {
  System.out.println(block.getId());
}
blockBlockByRefParams := gocardless.BlockBlockByRefParams{
  ReferenceType: "customer",
  ReferenceValue: "CU123",
  ReasonType: "no_intent_to_pay",
}

blockBlockByRefResult, err := client.Blocks.BlockByRef(ctx, blockBlockByRefParams)
for _, block := range blockBlockByRefResult.Blocks {
    fmt.Println(block.Id)
}
var resp = await client.Blocks.BlockByRefAsync(new GoCardless.Services.BlockBlockByRefRequest() {
  ReferenceType = "customer",
    ReferenceValue = "CU123",
    ReasonType = "no_intent_to_pay",
});
IReadOnlyList < GoCardless.Resources.Block > blocks = resp.Blocks;
Responsehttp
HTTP/1.1 201 Created
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "blocks": [
    {
      "id": "BLC123",
      "block_type": "email",
      "reason_type": "no_intent_to_pay",
      "resource_reference": "example@example.com",
      "active": true,
      "created_at": "2021-03-25T17:26:28.305Z",
      "updated_at": "2021-03-25T17:26:28.305Z"
    },
    {
      "id": "BLC456",
      "block_type": "bank_account",
      "reason_type": "no_intent_to_pay",
      "resource_reference": "BA123",
      "active": true,
      "created_at": "2021-03-25T17:26:28.305Z",
      "updated_at": "2021-03-25T17:26:28.305Z"
    }
  ]
}

POST https://api.gocardless.com/blocks/block_by_ref HTTP/1.1
Content-Type: application/json
{
  "blocks": {
    "reference_type": "customer",
    "reference_value": "CU123",
    "reason_type": "no_intent_to_pay"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "blocks": [
    {
      "id": "BLC123",
      "block_type": "email",
      "reason_type": "no_intent_to_pay",
      "resource_reference": "example@example.com",
      "active": true,
      "created_at": "2021-03-25T17:26:28.305Z",
      "updated_at": "2021-03-25T17:26:28.305Z"
    },
    {
      "id": "BLC456",
      "block_type": "bank_account",
      "reason_type": "no_intent_to_pay",
      "resource_reference": "BA123",
      "active": true,
      "created_at": "2021-03-25T17:26:28.305Z",
      "updated_at": "2021-03-25T17:26:28.305Z"
    }
  ]
}
Request Body
blocksobject
5 properties
reference_typestring

Type of entity we will seek to get the associated emails and bank accounts to create blocks from. This can currently be one of 'customer' or 'mandate'.

customermandate
reference_valuestring

This field is a reference to the entity you wish to block based on its emails and bank accounts. This may be the ID of a customer or a mandate. This means in order to block by reference the entity must have already been created as a resource.

reason_typestring

The reason you wish to block this payer, can currently be one of 'identity_fraud', 'no_intent_to_pay', 'unfair_chargeback'. If the reason isn't captured by one of the above then 'other' can be selected but you must provide a reason description.

identity_fraudno_intent_to_payunfair_chargebackother
reason_descriptionstring

This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.

activeboolean

Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.

Response 201

Resource created successfully

blocksarray
8 properties
idstring

Unique identifier, beginning with "BLC".

block_typestring

Type of entity we will seek to match against when blocking the mandate. This can currently be one of 'email', 'email_domain', 'bank_account', or 'bank_name'.

emailemail_domainbank_accountbank_name
reason_typestring

The reason you wish to block this payer, can currently be one of 'identity_fraud', 'no_intent_to_pay', 'unfair_chargeback'. If the reason isn't captured by one of the above then 'other' can be selected but you must provide a reason description.

identity_fraudno_intent_to_payunfair_chargebackother
reason_descriptionstring

This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.

resource_referencestring

This field is a reference to the value you wish to block. This may be the raw value (in the case of emails or email domains) or the ID of the resource (in the case of bank accounts and bank names). This means in order to block a specific bank account (even if you wish to block generically by name) it must already have been created as a resource.

activeboolean

Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.

created_atstring

Fixed timestamp, recording when this resource was created.

updated_atstring

Fixed timestamp, recording when this resource was updated.

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
SupportDashboard