GoCardlessDeveloper Docs
Create a sandbox account

Mandate Pdf

View as Markdown

Mandate PDFs allow you to easily display scheme-rules compliant Direct Debit mandates to your customers.

Create a mandate PDF#

POST/mandate_pdfs

Generates a PDF mandate and returns its temporary URL.

Customer and bank account details can be left blank (for a blank mandate), provided manually, or inferred from the ID of an existing mandate.

By default, we'll generate PDF mandates in English.

To generate a PDF mandate in another language, set the Accept-Language header when creating the PDF mandate to the relevant ISO 639-1 language code supported for the scheme.

SchemeSupported languages
ACHEnglish (en)
AutogiroEnglish (en), Swedish (sv)
BacsEnglish (en)
BECSEnglish (en)
BECS NZEnglish (en)
BetalingsserviceDanish (da), English (en)
PADEnglish (en)
SEPA CoreDanish (da), Dutch (nl), English (en), French (fr), German (de), Italian (it), Portuguese (pt), Spanish (es), Swedish (sv)
POST https://api.gocardless.com/mandate_pdfs HTTP/1.1
Content-Type: application/json
{
  "mandate_pdfs": {
    "links": {
      "mandate": "MD123"
    }
  }
}
@client.mandate_pdfs.create(
  params: {
    links: { mandate: "MD123" }
  }
)

@client.mandate_pdfs.create(
  params: {
    account_number: "55779911",
    branch_code: "200000",
    country_code: "GB"
  }
)

@client.mandate_pdfs.create(
  params: {
    iban: "FR14BARC20000055779911",
  },
  headers: {
    "Accept-Language" => "fr"
  }
)
client.mandate_pdfs.create(params={
  "links": {"mandate": "MD123"}
})

client.mandate_pdfs.create(params={
  "account_number": "44779911",
  "branch_code": "200000",
  "country_code": "GB"
})

client.mandate_pdfs.create(params={
  "iban": "FR14BARC20000055779911"
}, headers={
  "Accept-Language": "fr"
})
await client.mandatePdfs.create({
  links: {
    mandate: "MD123"
  }
});

await client.mandatePdfs.create(
  {
    links: {
      mandate: "MD123"
    }
  },
  "mandate_pdfs_idempotency_key"
);

await client.mandatePdfs.create(
  {
    account_number: "44779911",
    branch_code: "200000",
    country_code: "GB"
  },
  "",
  { "Accept-Language": "fr" }
);
$client->mandatePdfs()->create([
  "params" => ["links" => ["mandate" => "MD123"]]
]);

$client->mandatePdfs()->create([
  "params" => ["account_number" => "44779911",
               "branch_code" => "200000",
               "country_code" => "GB"]
]);

$client->mandatePdfs()->create([
        "params" => ["iban" => "FR14BARC20000055779911"],
        "headers" => ['accept-language' => 'fr']
]);
MandatePdf mandatePdfForMandate = client.mandatePdfs().create()
  .withLinksMandate("MD123")
  .execute();

MandatePdf mandatePdfForBankDetails = client.mandatePdfs().create()
  .withAccountNumber("44779911")
  .withBranchCode("200000")
  .withCountryCode("GB")
  .execute();

MandatePdf mandatePdfInFrench = client.mandatePdfs().create()
  .withIban("FR14BARC20000055779911")
  .withHeader("Accept-Language", "fr")
  .execute();
mandatePdfCreateParams := gocardless.MandatePdfCreateParams{
  Links: &gocardless.MandatePdfCreateParamsLinks{
    Mandate: "MD123",
  },
}

mandatePdf, err := client.MandatePdfs.Create(ctx, mandatePdfCreateParams)

requestOption := gocardless.WithIdempotencyKey("mandate_pdfs_idempotency_key")
mandatePdf, err = client.MandatePdfs.Create(ctx, mandatePdfCreateParams, requestOption)

headers := map[string]string{"Accept-Language": "fr"}
requestOption = gocardless.WithHeaders(headers)
mandatePdf, err = client.MandatePdfs.Create(ctx, mandatePdfCreateParams, requestOption)
var mandatePdfForMandateRequest = new GoCardless.Services.MandatePdfCreateRequest()
{
    Links = new GoCardless.Services.MandatePdfCreateRequest.MandatePdfLinks()
    {
        Mandate = "MD123"
    }
};

var mandatePdfForMandateResponse = await client.MandatePdfs.CreateAsync(mandatePdfForMandateRequest);
GoCardless.Resources.MandatePdf mandatePdfForMandate = mandatePdfForMandateResponse.MandatePdf;

var mandatePdfForBankDetailsRequest = new GoCardless.Services.MandatePdfCreateRequest()
{
    AccountNumber = "55779911",
    BranchCode = "200000",
    CountryCode = "GB"
};

var mandatePdfForBankDetailsResponse = await client.MandatePdfs.CreateAsync(mandatePdfForBankDetailsRequest);
GoCardless.Resources.MandatePdf mandatePdfForBankDetails = mandatePdfForBankDetailsResponse.MandatePdf;

var mandatePdfWithIbanRequest = new GoCardless.Services.MandatePdfCreateRequest()
{
    Iban = "FR14BARC20000055779911"
};

var mandatePdfWithIbanResponse = await client.MandatePdfs.CreateAsync(mandatePdfWithIbanRequest);
GoCardless.Resources.MandatePdf mandatePdfWithIban = mandatePdfWithIbanResponse.MandatePdf;

var requestSettings = new GoCardless.Internals.RequestSettings
{
    CustomiseRequestMessage = (request) =>
    {
      request.Headers.Add("Accept-Language", "fr");
    }
};

var frenchMandatePdfRequest = new GoCardless.Services.MandatePdfCreateRequest();
var frenchMandatePdfResponse = await client.MandatePdfs.CreateAsync(frenchMandatePdfRequest, requestSettings);
GoCardless.Resources.MandatePdf frenchMandatePdf = frenchMandatePdfResponse.MandatePdf;
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandate_pdfs": {
    "url": "https://mandate-previews.gocardless.com/?token=lhulxcPEbT9v3W0QUpBOxhlGUSYEayQQ4VVrpO7YnUKRYynP5",
    "expires_at": "2014-05-08T17:01:06.000Z"
  }
}

POST https://api.gocardless.com/mandate_pdfs HTTP/1.1
Content-Type: application/json
{
  "mandate_pdfs": {
    "account_number": "44779911",
    "branch_code": "200000",
    "country_code": "GB"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandate_pdfs": {
    "url": "https://mandate-previews.gocardless.com/?token=vlaPBHzSvm1OPwDNatZYWJCM7XZcCUuLPn7m5XV5",
    "expires_at": "2014-05-08T17:01:06.000Z"
  }
}

POST https://api.gocardless.com/mandate_pdfs HTTP/1.1
Content-Type: application/json
Accept-Language: fr
{
  "mandate_pdfs": {
    "iban": "FR14BARC20000055779911"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mandate_pdfs": {
    "url": "https://mandate-previews.gocardless.com/?token=vlaPBHzSvm1OPwDNatZYWJCM7XZcCUuLPn7m5XV5",
    "expires_at": "2014-05-08T17:01:06.000Z"
  }
}

POST https://api.gocardless.com/mandate_pdfs HTTP/1.1
Content-Type: application/json
{
  "mandate_pdfs": {
    "account_number": "44779911",
    "branch_code": "200000",
    "country_code": "GB",
    "links": {
      "mandate": "MD123"
    }
  }
}

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
  "error": {
    "message": "Cannot provide both a mandate and other details",
    "documentation_url": "https://developer.gocardless.com/api-reference#validation_failed",
    "type": "validation_failed",
    "request_id": "bd271b37-a2f5-47c8-b461-040dfe0e9cb1",
    "code": 422,
    "errors": [
      {
        "reason": "validation_failed",
        "message": "Cannot provide both a mandate and other details"
      }
    ]
  }
}
Request Body
mandate_pdfsobject
27 properties
schemestring

Direct Debit scheme. Can be supplied or automatically detected from the bank account details provided. If you do not provide a scheme, you must provide either a mandate, an iban, or local details including a country_code.

country_codestring

ISO 3166-1 alpha-2 code. Required if providing local details.

ibanstring

International Bank Account Number. Alternatively you can provide local details. IBANs cannot be provided for Autogiro mandates.

bicstring

SWIFT BIC. Will be derived automatically if a valid iban or local details are provided.

account_numberstring

Bank account number - see local details for more information. Alternatively you can provide an iban.

bank_codestring

Bank code - see local details for more information. Alternatively you can provide an iban.

branch_codestring

Branch code - see local details for more information. Alternatively you can provide an iban.

account_holder_namestring

Name of the account holder, as known by the bank. Usually this matches the name of the customer. This field cannot exceed 18 characters.

given_namestring

The customer's given name (i.e. first name). Used to populate the "Customer Name or Company name" field on the PDF. Ignored if company_name is provided.

family_namestring

The customer's family name (i.e. last name). Used to populate the "Customer Name or Company name" field on the PDF. Ignored if company_name is provided.

company_namestring

The customer's company name. Used to populate the "Customer Name or Company name" field on the PDF.

mandate_referencestring

Unique 6 to 18 character reference. This may be left blank at the point of signing.

signature_datestring

If provided, a form will be generated with this date and no signature field.

phone_numberstring

The customer phone number. Should only be provided for BECS NZ mandates.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Should only be supplied for Autogiro mandates.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Should only be supplied for Betalingsservice mandates.

address_line1string

The first line of the customer's address.

address_line2string

The second line of the customer's address.

address_line3string

The third line of the customer's address.

citystring

The city of the customer's address.

regionstring

The customer's address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g. CA for California).

postal_codestring

The customer's postal code.

account_typestring

Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.

savingschecking
payer_ip_addressstring

For American customers only. IP address of the computer used by the customer to set up the mandate. This is required in order to create compliant Mandate PDFs according to the ACH scheme rules.

subscription_amountobject

For American customers only. Subscription amount being authorised by the mandate. In the lowest denomination for the currency (cents in USD). Is required if subscription_frequency has been provided.

subscription_frequencystring

For American customers only. Frequency of the subscription being authorised by the mandate. One of weekly, monthly or yearly. Is required if subscription_amount has been provided.

weeklymonthlyyearly
linksobject
2 properties
mandatestring

ID of an existing mandate to build the PDF from. The customer's bank details will be censored in the generated PDF. No other parameters may be provided alongside this.

creditorstring

ID of an existing creditor. Only required if your account manages multiple creditors.

Response 201

Resource created successfully

mandate_pdfsobject
2 properties
urlstring

The URL at which this mandate PDF can be viewed until it expires at the date and time specified by expires_at. You should not store this URL or rely on its structure remaining the same.

expires_atstring

The date and time at which the url will expire (10 minutes after the original request).

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