Billing Request Template

View as Markdown

Billing Request Templates are reusable templates that result in numerous Billing Requests with similar attributes. They provide a no-code solution for generating various types of multi-user payment links.

Each template includes a reusable URL that can be embedded in a website or shared with customers via email. Every time the URL is opened, it generates a new Billing Request.

Billing Request Templates overcome the key limitation of the Billing Request: a Billing Request cannot be shared among multiple users because it is intended for single-use and is designed to cater to the unique needs of individual customers.

List Billing Request Templates#

GET/billing_request_templates

Returns a cursor-paginated list of your Billing Request Templates.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

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

@client.billing_request_templates.list

client.billing_request_templates.list().records

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

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

for (BillingRequestTemplate billingRequestTemplate : client.billingRequestTemplates().all().execute()) {
  System.out.println(billingRequestTemplate.getId());
}

billingRequestTemplateListParams := gocardless.BillingRequestTemplateListParams{}
billingRequestTemplateListResult, err := client.BillingRequestTemplates.List(ctx, billingRequestTemplateListParams)
for _, billingRequestTemplate := range billingRequestTemplateListResult.BillingRequestTemplates {
    fmt.Println(billingRequestTemplate.Id)
}

var billingRequestTemplateListResponse = client.BillingRequestTemplates.All();
foreach (GoCardless.Resources.BillingRequestTemplate billingRequestTemplate in billingRequestTemplateListResponse)
{
    Console.WriteLine(billingRequestTemplate.Id);
}

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "billing_request_templates": [
    {
      "id": "BRT123",
      "name": "12 Month Gold Plan",
      "mandate_request_currency": "GBP",
      "mandate_request_scheme": null,
      "mandate_request_verify": "recommended",
      "mandate_request_metadata": null,
      "payment_request_description": "One-time joining fee",
      "mandate_request_description": "Recurring fee",
      "mandate_request_constraints": {
        "max_amount_per_payment": 1000
      },
      "payment_request_amount": "69.99",
      "payment_request_currency": "GBP",
      "payment_request_scheme": null,
      "payment_request_metadata": null,
      "redirect_uri": "https://my-company.com/landing",
      "authorisation_url": "https://pay.gocardless.com/BRT123",
      "metadata": {
        "checkout-flow": "primary"
      },
      "created_at": "2021-07-27T17:10:33.784Z",
      "updated_at": "2021-07-27T17:10:33.784Z"
    }
  ]
}

Response 200

Successful response

billing_request_templatesarray

18 properties

idstring

Unique identifier, beginning with "BRT".

namestring

Name for the template. Provides a friendly human name for the template, as it is shown in the dashboard. Must not exceed 255 characters.

mandate_request_currencyobject

ISO 4217 currency code.

mandate_request_schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported. Optional for mandate only requests - if left blank, the payer will be able to select the currency/scheme to pay with from a list of your available schemes.

mandate_request_verifyobject

Verification preference for the mandate.

mandate_request_metadataobject

Key-value store of custom data that will be applied to the mandate created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

payment_request_descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

mandate_request_descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

mandate_request_constraintsobject

Constraints that will apply to the mandate_request. (Optional) Specifically required for PayTo and VRP.

5 properties

start_datestring

The date from which payments can be taken.

This is an optional field and if it is not supplied the start date will be set to the day authorisation happens.

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

This is an optional field and if it is not supplied the agreement will be considered open and will not have an end date. Keep in mind the end date must take into account how long it will take the user to set up this agreement via the Billing Request.

max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). Note: Required for PayTo and VRP.

payment_methodstring

A constraint where you can specify info (free text string) about how payments are calculated. For use when payments vary and cannot be expressed as a fixed amount and frequency. Note: This is only supported for ACH and PAD schemes.

periodic_limitsarray

Caps on the total amount and/or number of payments that can be collected within a repeating period (e.g. no more than a set amount per month), as opposed to max_amount_per_payment which caps a single payment.

Note: Required for VRP, where exactly one periodic limit must be provided. Optional for PayTo.

4 properties

periodstring

The repeating period for this mandate. Required whenever a periodic limit is provided (for both VRP and PayTo). If periodic_limits is omitted entirely for PayTo, this defaults to flexible.

dayweekmonthyearflexible

max_total_amountinteger

The maximum total amount that can be charged for all payments in this periodic limit, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Note: Required for VRP. This is not permitted for the PayTo scheme.

max_paymentsinteger

The maximum number of payments that can be collected in this periodic limit.

Note: Only supported for the PayTo scheme, where it is optional.

alignmentstring

The alignment of the period. Defaults to creation_date if not specified.

calendar - the period follows fixed calendar boundaries, the same for every mandate: week runs Monday to Sunday, month runs from the 1st to the last day of the calendar month, and year runs from 1 January to 31 December. If the mandate starts partway through a period, the limit for that first period is reduced proportionally to the days remaining (e.g. a monthly limit starting on the 15th gives roughly half the limit for that first month).

creation_date - the period follows the mandate's own start date rather than the calendar. For example, if the mandate starts on the 15th, each monthly period runs from the 15th to the 14th of the following month. The first period is a full period, not reduced proportionally.

Note: Has no effect when period is flexible.

calendarcreation_date

payment_request_amountstring

Amount in full.

payment_request_currencyobject

ISO 4217 currency code. GBP and EUR supported; GBP with your customers in the UK and for EUR with your customers in supported Eurozone countries only.

payment_request_schemestring

(Optional) A scheme used for Open Banking payments. Currently faster_payments is supported in the UK (GBP) and sepa_credit_transfer and sepa_instant_credit_transfer are supported in supported Eurozone countries (EUR). For Eurozone countries, sepa_credit_transfer is used as the default. Please be aware that sepa_instant_credit_transfer may incur an additional fee for your customer.

payment_request_metadataobject

Key-value store of custom data that will be applied to the payment created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

redirect_uristring

URL that the payer can be redirected to after completing the request flow.

authorisation_urlstring

Permanent URL that customers can visit to allow them to complete a flow based on this template, before being returned to the redirect_uri.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

created_atstring

Fixed timestamp, recording when this resource was created.

updated_atstring

Dynamic timestamp recording when this resource was last 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

request_idstring

typestring

metadataobject

linksobject

Create a Billing Request Template#

POST/billing_request_templates

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/billing_request_templates HTTP/1.1
Content-Type: application/json
{
  "billing_request_templates": {
    "name": "12 Month Gold Plan",
    "payment_request_description": "One-time joining fee",
    "mandate_request_description": "Recurring fee",
    "mandate_request_constraints": {
      "max_amount_per_payment": 1000
    },
    "payment_request_currency": "GBP",
    "payment_request_amount": "69.99",
    "mandate_request_currency": "GBP",
    "redirect_uri": "https://my-company.com/landing",
    "metadata": {
      "checkout-flow": "primary"
    }
  }
}

@client.billing_request_templates.create(
  params: {
    name: "12 Month Gold Plan",
    payment_request_description: "One-time joining fee",
    mandate_request_description: "Recurring fee",
    payment_request_currency: "GBP",
    payment_request_amount: "69.99",
    mandate_request_currency: "GBP",
    redirect_uri: "https://my-company.com/landing",
  }
)

client.billing_request_templates.create(params={
  "name": "12 Month Gold Plan",
  "payment_request_description": "One-time joining fee",
  "mandate_request_description": "Recurring fee",
  "payment_request_currency": "GBP",
  "payment_request_amount": "69.99",
  "mandate_request_currency": "GBP",
  "redirect_uri": "https://my-company.com/landing",
})

const billingRequestTemplate = await client.billingRequestTemplates.create({
  name: "12 Month Gold Plan",
  payment_request_description: "One-time joining fee",
  mandate_request_description: "Recurring fee",
  payment_request_currency: "GBP",
  payment_request_amount: "69.99",
  mandate_request_currency: "GBP",
  redirect_uri: "https://my-company.com/landing",
});

$client->billingRequestTemplates()->create([
  "params" => [
    "name" => "12 Month Gold Plan",
    "payment_request_description" => "One-time joining fee",
    "mandate_request_description" => "Recurring fee",
    "payment_request_currency" => "GBP",
    "payment_request_amount" => "69.99",
    "mandate_request_currency" => "GBP",
    "redirect_uri" => "https://my-company.com/landing",
  ]
]);

BillingRequestTemplate billingRequestTemplate = client.billingRequestTemplates().create()
  .withPaymentRequestDescription("One-time joining fee")
  .withPaymentRequestCurrency("GBP")
  .withPaymentRequestAmount("69.99")
  .withMandateRequestCurrency("GBP")
  .withRedirectUri("https://my-company.com/landing")
  .execute();

billingRequestTemplateCreateParams := gocardless.BillingRequestTemplateCreateParams{
  Name:                      "12 Month Gold Plan",
  PaymentRequestDescription: "One-time joining fee",
  PaymentRequestCurrency:    "GBP",
  PaymentRequestAmount:      "6999",
  MandateRequestCurrency:    "GBP",
  RedirectUri:               "https://my-company.com/landing",
}

billingRequestTemplate, err := client.BillingRequestTemplates.Create(ctx, billingRequestTemplateCreateParams)

var resp = await client.BillingRequestTemplates.CreateAsync(
  new GoCardless.Services.BillingRequestTemplateCreateRequest()
  {
    PaymentRequestDescription = "One-time joining fee",
    PaymentRequestCurrency = "GBP",
    PaymentRequestAmount = "6999",
    MandateRequestCurrency = "GBP",
    RedirectUri = "https://my-company.com/landing",
  }
);

GoCardless.Resources.BillingRequestTemplate billingRequestTemplate = resp.BillingRequestTemplate;

Responsehttp

HTTP/1.1 201 Created
Location: /billing_request_templates/BRT123
Content-Type: application/json
{
  "billing_request_templates": {
    "id": "BRT123",
    "name": "12 Month Gold Plan",
    "mandate_request_currency": "GBP",
    "mandate_request_scheme": null,
    "mandate_request_verify": "recommended",
    "mandate_request_metadata": null,
    "payment_request_description": "One-time joining fee",
    "mandate_request_description": "Recurring fee",
    "mandate_request_constraints": {
      "max_amount_per_payment": 1000
    },
    "payment_request_amount": "69.99",
    "payment_request_currency": "GBP",
    "payment_request_scheme": null,
    "payment_request_metadata": null,
    "redirect_uri": "https://my-company.com/landing",
    "authorisation_url": "https://pay.gocardless.com/BRT123",
    "metadata": {
      "checkout-flow": "primary"
    },
    "created_at": "2021-07-27T17:10:33.784Z",
    "updated_at": "2021-07-27T17:10:33.784Z"
  }
}

Request Body

billing_request_templatesobject

15 properties

namestring

Name for the template. Provides a friendly human name for the template, as it is shown in the dashboard. Must not exceed 255 characters.

mandate_request_currencyobject

ISO 4217 currency code.

mandate_request_schemestring

mandate_request_verifystring

Verification preference for the mandate.

mandate_request_metadataobject

payment_request_descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

mandate_request_descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

mandate_request_constraintsobject

Constraints that will apply to the mandate_request. (Optional) Specifically required for PayTo and VRP.

5 properties

start_datestring

The date from which payments can be taken.

This is an optional field and if it is not supplied the start date will be set to the day authorisation happens.

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). Note: Required for PayTo and VRP.

payment_methodstring

periodic_limitsarray

Note: Required for VRP, where exactly one periodic limit must be provided. Optional for PayTo.

4 properties

periodstring

The repeating period for this mandate. Required whenever a periodic limit is provided (for both VRP and PayTo). If periodic_limits is omitted entirely for PayTo, this defaults to flexible.

dayweekmonthyearflexible

max_total_amountinteger

The maximum total amount that can be charged for all payments in this periodic limit, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Note: Required for VRP. This is not permitted for the PayTo scheme.

max_paymentsinteger

The maximum number of payments that can be collected in this periodic limit.

Note: Only supported for the PayTo scheme, where it is optional.

alignmentstring

The alignment of the period. Defaults to creation_date if not specified.

Note: Has no effect when period is flexible.

calendarcreation_date

payment_request_amountstring

Amount in full.

payment_request_currencyobject

ISO 4217 currency code. GBP and EUR supported; GBP with your customers in the UK and for EUR with your customers in supported Eurozone countries only.

payment_request_schemestring

payment_request_metadataobject

redirect_uristring

URL that the payer can be redirected to after completing the request flow.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

linksobject

1 properties

creditorstring

ID of the associated creditor. Only required if your account manages multiple creditors.

Response 201

Resource created successfully

billing_request_templatesobject

18 properties

idstring

Unique identifier, beginning with "BRT".

namestring

Name for the template. Provides a friendly human name for the template, as it is shown in the dashboard. Must not exceed 255 characters.

mandate_request_currencyobject

ISO 4217 currency code.

mandate_request_schemestring

mandate_request_verifyobject

Verification preference for the mandate.

mandate_request_metadataobject

payment_request_descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

mandate_request_descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

mandate_request_constraintsobject

Constraints that will apply to the mandate_request. (Optional) Specifically required for PayTo and VRP.

5 properties

start_datestring

The date from which payments can be taken.

This is an optional field and if it is not supplied the start date will be set to the day authorisation happens.

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). Note: Required for PayTo and VRP.

payment_methodstring

periodic_limitsarray

Note: Required for VRP, where exactly one periodic limit must be provided. Optional for PayTo.

4 properties

periodstring

The repeating period for this mandate. Required whenever a periodic limit is provided (for both VRP and PayTo). If periodic_limits is omitted entirely for PayTo, this defaults to flexible.

dayweekmonthyearflexible

max_total_amountinteger

The maximum total amount that can be charged for all payments in this periodic limit, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Note: Required for VRP. This is not permitted for the PayTo scheme.

max_paymentsinteger

The maximum number of payments that can be collected in this periodic limit.

Note: Only supported for the PayTo scheme, where it is optional.

alignmentstring

The alignment of the period. Defaults to creation_date if not specified.

Note: Has no effect when period is flexible.

calendarcreation_date

payment_request_amountstring

Amount in full.

payment_request_currencyobject

ISO 4217 currency code. GBP and EUR supported; GBP with your customers in the UK and for EUR with your customers in supported Eurozone countries only.

payment_request_schemestring

payment_request_metadataobject

redirect_uristring

URL that the payer can be redirected to after completing the request flow.

authorisation_urlstring

Permanent URL that customers can visit to allow them to complete a flow based on this template, before being returned to the redirect_uri.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

created_atstring

Fixed timestamp, recording when this resource was created.

updated_atstring

Dynamic timestamp recording when this resource was last 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

request_idstring

typestring

metadataobject

linksobject

Get a single Billing Request Template#

GET/billing_request_templates/{billing_request_template_id}

Fetches a Billing Request Template

Path Parameters

Name	Type	Description
`billing_request_template_id`required	string	The billing request template id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/billing_request_templates/BRT123 HTTP/1.1

@client.billing_request_templates.get("BRT123")

client.billing_request_templates.get("BRT123")

const resp = await client.billingRequestTemplates.find("BRT123");

$client->billingRequestTemplates()->get("BRT123");

client.billingRequestTemplates().get("BRT123").execute();

billingRequestTemplate, err := client.BillingRequestTemplates.Get(ctx, "BRT123")

var resp = await client.BillingRequestTemplates.GetAsync("BRT123");

Responsehttp

HTTP/1.1 200
Content-Type: application/json
{
  "billing_request_templates": {
    "id": "BRT123",
    "name": "12 Month Gold Plan",
    "mandate_request_currency": "GBP",
    "mandate_request_scheme": null,
    "mandate_request_verify": "recommended",
    "mandate_request_metadata": null,
    "payment_request_description": "One-time joining fee",
    "mandate_request_description": "Recurring fee",
    "mandate_request_constraints": {
      "max_amount_per_payment": 1000
    },
    "payment_request_amount": "69.99",
    "payment_request_currency": "GBP",
    "payment_request_scheme": null,
    "payment_request_metadata": null,
    "redirect_uri": "https://my-company.com/landing",
    "authorisation_url": "https://pay.gocardless.com/BRT123",
    "metadata": {
      "checkout-flow": "primary"
    },
    "created_at": "2021-07-27T17:10:33.784Z",
    "updated_at": "2021-07-27T17:10:33.784Z"
  }
}

Response 200

Successful response

billing_request_templatesobject

18 properties

idstring

Unique identifier, beginning with "BRT".

namestring

Name for the template. Provides a friendly human name for the template, as it is shown in the dashboard. Must not exceed 255 characters.

mandate_request_currencyobject

ISO 4217 currency code.

mandate_request_schemestring

mandate_request_verifyobject

Verification preference for the mandate.

mandate_request_metadataobject

payment_request_descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

mandate_request_descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

mandate_request_constraintsobject

Constraints that will apply to the mandate_request. (Optional) Specifically required for PayTo and VRP.

5 properties

start_datestring

The date from which payments can be taken.

This is an optional field and if it is not supplied the start date will be set to the day authorisation happens.

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). Note: Required for PayTo and VRP.

payment_methodstring

periodic_limitsarray

Note: Required for VRP, where exactly one periodic limit must be provided. Optional for PayTo.

4 properties

periodstring

The repeating period for this mandate. Required whenever a periodic limit is provided (for both VRP and PayTo). If periodic_limits is omitted entirely for PayTo, this defaults to flexible.

dayweekmonthyearflexible

max_total_amountinteger

The maximum total amount that can be charged for all payments in this periodic limit, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Note: Required for VRP. This is not permitted for the PayTo scheme.

max_paymentsinteger

The maximum number of payments that can be collected in this periodic limit.

Note: Only supported for the PayTo scheme, where it is optional.

alignmentstring

The alignment of the period. Defaults to creation_date if not specified.

Note: Has no effect when period is flexible.

calendarcreation_date

payment_request_amountstring

Amount in full.

payment_request_currencyobject

ISO 4217 currency code. GBP and EUR supported; GBP with your customers in the UK and for EUR with your customers in supported Eurozone countries only.

payment_request_schemestring

payment_request_metadataobject

redirect_uristring

URL that the payer can be redirected to after completing the request flow.

authorisation_urlstring

Permanent URL that customers can visit to allow them to complete a flow based on this template, before being returned to the redirect_uri.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

created_atstring

Fixed timestamp, recording when this resource was created.

updated_atstring

Dynamic timestamp recording when this resource was last 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

request_idstring

typestring

metadataobject

linksobject

Update a Billing Request Template#

PUT/billing_request_templates/{billing_request_template_id}

Updates a Billing Request Template, which will affect all future Billing Requests created by this template.

Path Parameters

Name	Type	Description
`billing_request_template_id`required	string	The billing request template id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

PUT https://api.gocardless.com/billing_request_templates/BRT123 HTTP/1.1
Content-Type: application/json
{
  "billing_request_templates": {
    "name": "12 Month Silver Plan",
    "payment_request_amount": "49.99"
  }
}

@client.billing_request_templates.update("BRT123", params: {
  name: "12 Month Silver Plan",
  payment_request_amount: "49.99",
})

client.billing_request_templates.update("BRT123", params={
  "name": "12 Month Silver Plan",
  "payment_request_amount": "49.99",
})

const billingRequestTemplate = await client.billingRequestTemplates.update("BRT123", {
  name: "12 Month Silver Plan",
  payment_request_amount: "49.99",
});

$client->billingRequestTemplates()->update("BRT123", [
  "params" => [
    "name" => "12 Month Silver Plan",
    "payment_request_amount" => "49.99"
  ]
]);

BillingRequestTemplate billingRequestTemplate = client.billingRequestTemplates().update("BRT123")
  .withName("12 Month Silver Plan")
  .withPaymentRequestAmount("49.99")
  .execute();

billingRequestTemplateUpdateParams := gocardless.BillingRequestTemplateUpdateParams{
  Name:                 "12 Month Silver Plan",
  PaymentRequestAmount: "4999",
}

billingRequestTemplate, err := client.BillingRequestTemplates.Update(ctx, "BRT123", billingRequestTemplateUpdateParams)

var resp = await client.BillingRequestTemplates.UpdateAsync(
  "BRT123",
  new GoCardless.Services.BillingRequestTemplateUpdateRequest()
  {
    Name = "12 Month Silver Plan",
    PaymentRequestAmount = "4999",
  }
);

GoCardless.Resources.BillingRequestTemplate billingRequestTemplate = resp.BillingRequestTemplate;

Responsehttp

HTTP/1.1 200 OK
Location: /billing_request_templates/BRT123
Content-Type: application/json
{
  "billing_request_templates": {
    "id": "BRT123",
    "name": "12 Month Silver Plan",
    "mandate_request_currency": "GBP",
    "mandate_request_scheme": null,
    "mandate_request_verify": "recommended",
    "mandate_request_metadata": null,
    "payment_request_description": "One-time joining fee",
    "mandate_request_description": "Recurring fee",
    "mandate_request_constraints": {
      "max_amount_per_payment": 1000
    },
    "payment_request_amount": "49.99",
    "payment_request_currency": "GBP",
    "payment_request_scheme": null,
    "payment_request_metadata": null,
    "redirect_uri": "https://my-company.com/landing",
    "authorisation_url": "https://pay.gocardless.com/BRT123",
    "metadata": {
      "checkout-flow": "primary"
    },
    "created_at": "2021-07-27T17:10:33.784Z",
    "updated_at": "2021-07-30T11:28:11.123Z"
  }
}

Request Body

billing_request_templatesobject

14 properties

namestring

Name for the template. Provides a friendly human name for the template, as it is shown in the dashboard. Must not exceed 255 characters.

mandate_request_currencyobject

ISO 4217 currency code.

mandate_request_schemestring

mandate_request_verifystring

Verification preference for the mandate.

mandate_request_metadataobject

payment_request_descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

mandate_request_descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

mandate_request_constraintsobject

Constraints that will apply to the mandate_request. (Optional) Specifically required for PayTo and VRP.

5 properties

start_datestring

The date from which payments can be taken.

This is an optional field and if it is not supplied the start date will be set to the day authorisation happens.

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). Note: Required for PayTo and VRP.

payment_methodstring

periodic_limitsarray

Note: Required for VRP, where exactly one periodic limit must be provided. Optional for PayTo.

4 properties

periodstring

The repeating period for this mandate. Required whenever a periodic limit is provided (for both VRP and PayTo). If periodic_limits is omitted entirely for PayTo, this defaults to flexible.

dayweekmonthyearflexible

max_total_amountinteger

The maximum total amount that can be charged for all payments in this periodic limit, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Note: Required for VRP. This is not permitted for the PayTo scheme.

max_paymentsinteger

The maximum number of payments that can be collected in this periodic limit.

Note: Only supported for the PayTo scheme, where it is optional.

alignmentstring

The alignment of the period. Defaults to creation_date if not specified.

Note: Has no effect when period is flexible.

calendarcreation_date

payment_request_amountstring

Amount in full.

payment_request_currencyobject

ISO 4217 currency code. GBP and EUR supported; GBP with your customers in the UK and for EUR with your customers in supported Eurozone countries only.

payment_request_schemestring

payment_request_metadataobject

redirect_uristring

URL that the payer can be redirected to after completing the request flow.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Response 200

Successful response

billing_request_templatesobject

18 properties

idstring

Unique identifier, beginning with "BRT".

namestring

Name for the template. Provides a friendly human name for the template, as it is shown in the dashboard. Must not exceed 255 characters.

mandate_request_currencyobject

ISO 4217 currency code.

mandate_request_schemestring

mandate_request_verifyobject

Verification preference for the mandate.

mandate_request_metadataobject

payment_request_descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

mandate_request_descriptionstring

A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.

mandate_request_constraintsobject

Constraints that will apply to the mandate_request. (Optional) Specifically required for PayTo and VRP.

5 properties

start_datestring

The date from which payments can be taken.

This is an optional field and if it is not supplied the start date will be set to the day authorisation happens.

end_datestring

The latest date at which payments can be taken, must occur after start_date if present

max_amount_per_paymentinteger

The maximum amount that can be charged for a single payment in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). Note: Required for PayTo and VRP.

payment_methodstring

periodic_limitsarray

Note: Required for VRP, where exactly one periodic limit must be provided. Optional for PayTo.

4 properties

periodstring

The repeating period for this mandate. Required whenever a periodic limit is provided (for both VRP and PayTo). If periodic_limits is omitted entirely for PayTo, this defaults to flexible.

dayweekmonthyearflexible

max_total_amountinteger

The maximum total amount that can be charged for all payments in this periodic limit, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

Note: Required for VRP. This is not permitted for the PayTo scheme.

max_paymentsinteger

The maximum number of payments that can be collected in this periodic limit.

Note: Only supported for the PayTo scheme, where it is optional.

alignmentstring

The alignment of the period. Defaults to creation_date if not specified.

Note: Has no effect when period is flexible.

calendarcreation_date

payment_request_amountstring

Amount in full.

payment_request_currencyobject

ISO 4217 currency code. GBP and EUR supported; GBP with your customers in the UK and for EUR with your customers in supported Eurozone countries only.

payment_request_schemestring

payment_request_metadataobject

redirect_uristring

URL that the payer can be redirected to after completing the request flow.

authorisation_urlstring

Permanent URL that customers can visit to allow them to complete a flow based on this template, before being returned to the redirect_uri.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

created_atstring

Fixed timestamp, recording when this resource was created.

updated_atstring

Dynamic timestamp recording when this resource was last 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

request_idstring

typestring

metadataobject

linksobject