GoCardlessDeveloper Docs
Create a sandbox account

Payer Authorisation

View as Markdown

Don't use Payer Authorisations for new integrations. It is deprecated in favour of Billing Requests. Use Billing Requests to build any future integrations.

Payer Authorisation resource acts as a wrapper for creating customer, bank account and mandate details in a single request. PayerAuthorisation API enables the integrators to build their own custom payment pages.

The process to use the Payer Authorisation API is as follows:

  1. Create a Payer Authorisation, either empty or with already available information
  2. Update the authorisation with additional information or fix any mistakes
  3. Submit the authorisation, after the payer has reviewed their information
  4. [coming soon] Redirect the payer to the verification mechanisms from the response of the Submit request (this will be introduced as a non-breaking change)
  5. Confirm the authorisation to indicate that the resources can be created

After the Payer Authorisation is confirmed, resources will eventually be created as it's an asynchronous process.

To retrieve the status and ID of the linked resources you can do one of the following:

  1. Listen to payer_authorisation_completed webhook (recommended)
  2. Poll the GET endpoint
  3. Poll the GET events API https://api.gocardless.com/events?payer_authorisation={id}&action=completed

Get a single Payer Authorisation#

GET/payer_authorisations/{payer_authorisation_id}

Retrieves the details of a single existing Payer Authorisation. It can be used for polling the status of a Payer Authorisation.

Deprecated: Payer Authorisation is legacy API and cannot be used by new integrators. The Billing Request API should be used for any new integrations.

Path Parameters

NameTypeDescription
payer_authorisation_idrequiredstring

The payer authorisation id

GET https://api.gocardless.com/payer_authorisations/PAU123 HTTP/1.1
@client.payer_authorisations.get("PAU123")
client.payer_authorisations.get("PAU123")
const payerAuthorisation = await client.payerAuthorisations.find("PAU123");
$client->payerAuthorisations()->get("PAU123");
PayerAuthorisation payerAuthorisation = client.payerAuthorisations().get("PAU123").execute();
payerAuthorisation, err := client.PayerAuthorisations.Get(ctx, "PAU123")
var payerAuthorisationResponse = await client.PayerAuthorisations.GetAsync("PAU123");
GoCardless.Resources.PayerAuthorisation payerAuthorisation = payerAuthorisationResponse.PayerAuthorisation;
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
"payer_authorisations": {
    "id": "PAU123",
    "created_at": "2020-09-11T14:04:50.579Z",
    "customer": {
        "address_line1": "Unit 12, 2 Somerset Road",
        "address_line2": "terertertre",
        "city": "London",
        "company_name": "",
        "country_code": "US",
        "email": "mail@example.com",
        "family_name": "test",
        "given_name": "lastname",
        "postal_code": "1234",
        "region": "AR",
        "metadata": {}
    },
    "bank_account": {
        "account_holder_name": "test lastname",
        "account_number_ending": "11",
        "account_type": "savings",
        "country_code": "US",
        "metadata": {}
    },
    "mandate": {
        "scheme": "ach",
        "metadata": {}
    },
    "status": "completed",
    "incomplete_fields": [],
    "links": {
      "customer": "CU00123",
      "bank_account": "BA00123",
      "mandate": "MD000123"
    }
  }
}
Response 200

Successful response

payer_authorisationsobject
8 properties
idstring

Unique identifier, beginning with "PA".

created_atstring

Timestamp, recording when this Payer Authorisation was created.

customerobject

All details required for the creation of a Customer.

15 properties
emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

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.

country_codestring

ISO 3166-1 alpha-2 code.

localestring

An IETF Language Tag, used for both language and regional variations of our product.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

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.

bank_accountobject

All details required for the creation of a Customer Bank Account.

11 properties
account_holder_namestring

Name of the account holder, as known by the bank. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. This field is required unless the request includes a customer bank account token.

account_numberstring

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

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_number_suffixstring

Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.

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.

ibanstring

International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

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

mandateobject

All details required for the creation of a Mandate.

4 properties
referencestring

Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_core
payer_ip_addressstring

For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

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.

incomplete_fieldsarray

An array of fields which are missing and is required to set up the mandate.

3 properties
fieldstring

The root resource.

messagestring

A localised error message

request_pointerstring

The path to the field e.g. "/payer_authorisations/customer/city"

linksobject

IDs of the created resources. Available after the Payer Authorisation is completed.

3 properties
customerstring

Unique identifier, beginning with "CU".

bank_accountstring

Unique identifier, beginning with "BA".

mandatestring

Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.

statusstring

One of:

  • created: The PayerAuthorisation has been created, and not been confirmed yet
  • submitted: The payer information has been submitted
  • confirmed: PayerAuthorisation is confirmed and resources are ready to be created
  • completed: The PayerAuthorisation has been completed and customer, bank_account and mandate has been created
  • failed: The PayerAuthorisation has failed and customer, bank_account and mandate is not created
createdsubmittedconfirmedcompletedfailed
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

Update a Payer Authorisation#

PUT/payer_authorisations/{payer_authorisation_id}

Updates a Payer Authorisation. Updates the Payer Authorisation with the request data. Can be invoked as many times as needed. Only fields present in the request will be modified. An empty array of incomplete_fields means that the resource is valid. This endpoint has been designed this way so you do not need to save any payer data on your servers or the browser while still being able to implement a progressive solution, such a multi-step form.

Note that in order to update the metadata attribute values it must be sent completely as it overrides the previously existing values.

Deprecated: Payer Authorisation is legacy API and cannot be used by new integrators. The Billing Request API should be used for any new integrations.

Path Parameters

NameTypeDescription
payer_authorisation_idrequiredstring

The payer authorisation id

PUT https://api.gocardless.com/payer_authorisations/PA123 HTTP/1.1
Content-Type: application/json
{
  "payer_authorisations": {
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911"
    },
    "mandate": {
      "reference": "XYZ789"
    }
  }
}

Example response with incomplete fields
@client.payer_authorisations.update(
  "PA123",
  params: {
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911",
    },
    "mandate": {
      "reference": "XYZ789",
    }
  }
)
client.payer_authorisations.update("PA123", params={
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911",
    },
    "mandate": {
      "reference": "XYZ789",
    }
})
const payerAuthorisation = await client.payerAuthorisations.update(
  "PA123",
  {
    "customer": {
        "email": "mail@example.com",
        "given_name": "Name",
        "family_name": "Surname",
        "metadata": {
          "salesforce_id": "EFGH5678"
        }
      },
      "bank_account": {
        "account_holder_name": "Name Surname",
        "branch_code": "200000",
        "account_number": "55779911",
        "metadata": {}
      },
      "mandate": {
        "reference": "XYZ789",
        "metadata": {}
      }
  });
$client->payerAuthorisations()->update("PA123", [
  "params" => ["customer" => [
      "email" => "mail@example.com",
      "given_name" => "Name",
      "family_name" => "Surname",
      "metadata" => [
        "salesforce_id" => "EFGH5678"
      ]
    ],
    "bank_account" => [
      "account_holder_name" => "Name Surname",
      "branch_code" => "200000",
      "account_number" => "55779911",
    ],
    "mandate" => [
      "reference" => "XYZ789",
    ]]
]);
import java.util.HashMap;
import java.util.Map;

Map<String, String> customerMetadata = new HashMap<>();
customerMetadata.put("salesforce_id", "EFGH5678");
PayerAuthorisation payerAuthorisation = client.payerAuthorisations().update("PA123")
  .withCustomerEmail("mail@example.com")
  .withCustomerGivenName("Name")
  .withCustomerFamilyName("Surname")
  .withCustomerMetadata(customerMetadata)
  .withBankAccountAccountHolderName("Name Surname")
  .withBankAccountBranchCode("200000")
  .withBankAccountAccountNumber("55779911")
  .withMandateReference("XYZ789")
  .execute();
payerAuthorisationUpdateParams := gocardless.PayerAuthorisationUpdateParams{
  Customer: gocardless.PayerAuthorisationUpdateParamsCustomer{
    Email:      "mail@example.com",
    GivenName:  "Name",
    FamilyName: "Surname",
    Metadata:   map[string]string{"salesforce_id": "EFGH5678"},
  },
  BankAccount: gocardless.PayerAuthorisationUpdateParamsBankAccount{
    AccountHolderName: "Name Surname",
    BranchCode:        "200000",
    AccountNumber:     "55779911",
  },
  Mandate: gocardless.PayerAuthorisationUpdateParamsMandate{
    Reference: "XYZ789",
  },
}

payerAuthorisation, err := client.PayerAuthorisations.Update(ctx, "PA123", payerAuthorisationUpdateParams)
var customer = new GoCardless.Services.PayerAuthorisationUpdateRequest.PayerAuthorisationCustomer()
{
  Email = "mail@example.com",
  GivenName = "Name",
  FamilyName = "Surname",
  Metadata = new Dictionary<string, string> {
    {"salesforce_id", "EFGH5678"}
  }
};
var bankAccount = new GoCardless.Services.PayerAuthorisationUpdateRequest.PayerAuthorisationBankAccount()
{
  AccountHolderName = "Name Surname",
  BranchCode = "200000",
  AccountNumber = "55779911"
};
var mandate = new GoCardless.Services.PayerAuthorisationUpdateRequest.PayerAuthorisationMandate()
{
  Reference = "XYZ789"
};
var PayerAuthorisationRequest = new GoCardless.Services.PayerAuthorisationUpdateRequest()
{
    Customer = customer,
    BankAccount = bankAccount,
    Mandate = mandate
};
var PayerAuthorisationResponse = await client.PayerAuthorisations.UpdateAsync("PA123", PayerAuthorisationRequest);
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "payer_authorisations": {
    "id": "PA123",
    "created_at": "2020-04-15T15:00:00.000Z",
    "status": "created",
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "account_number_ending": "11",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    },
    "links": {},
    "incomplete_fields":[
      {
        "field": "payer_authorisations",
        "message": "is required",
        "request_pointer": "/payer_authorisations/customer/address_line1"
      },
      {
        "field": "payer_authorisations",
        "message": "is required",
        "request_pointer": "/payer_authorisations/customer/city"
      },
      {
        "field": "payer_authorisations",
        "message": "is required",
        "request_pointer": "/payer_authorisations/customer/postal_code"
      }
    ]
  }
}

Example response where Payer Authorisation is updated after submitting

HTTP/1.1 422 Bad Request
Content-Type: application/json
{
  "error": {
    "message": "The Payer Authorisation cannot be updated after submitted",
    "errors": [
        {
            "reason": "payer_authorisation_cannot_update_after_submit",
            "message": "The Payer Authorisation cannot be updated after submitting"
        }
    ],
    "documentation_url": "https://developer.gocardless.com/api-reference#payer_authorisation_cannot_update_after_submit",
    "type": "invalid_state",
    "request_id": "...",
    "code": 422
  }
}

 Example response with errors

HTTP/1.1 422 Unprocessable entity
Content-Type: application/json
{

  "error": {
      "message": "Validation failed",
      "errors": [
          {
              "field": "customer",
              "message": "is not valid",
              "request_pointer": "/payer_authorisations/customer/email"
          }
      ],
      "documentation_url": "https://developer.gocardless.com/api-reference#validation_failed",
      "type": "validation_failed",
      "request_id": "2f0db86c-251c-432a-a7af-b77f1a426a37",
      "code": 422
  }

}
Request Body
payer_authorisationsobject
3 properties
customerobject

All details required for the creation of a Customer.

15 properties
emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

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.

country_codestring

ISO 3166-1 alpha-2 code.

localestring

An IETF Language Tag, used for both language and regional variations of our product.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

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.

bank_accountobject

All details required for the creation of a Customer Bank Account.

11 properties
account_holder_namestring

Name of the account holder, as known by the bank. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. This field is required unless the request includes a customer bank account token.

account_numberstring

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

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_number_suffixstring

Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.

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.

ibanstring

International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

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

mandateobject

All details required for the creation of a Mandate.

4 properties
referencestring

Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_core
payer_ip_addressstring

For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

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

payer_authorisationsobject
8 properties
idstring

Unique identifier, beginning with "PA".

created_atstring

Timestamp, recording when this Payer Authorisation was created.

customerobject

All details required for the creation of a Customer.

15 properties
emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

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.

country_codestring

ISO 3166-1 alpha-2 code.

localestring

An IETF Language Tag, used for both language and regional variations of our product.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

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.

bank_accountobject

All details required for the creation of a Customer Bank Account.

11 properties
account_holder_namestring

Name of the account holder, as known by the bank. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. This field is required unless the request includes a customer bank account token.

account_numberstring

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

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_number_suffixstring

Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.

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.

ibanstring

International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

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

mandateobject

All details required for the creation of a Mandate.

4 properties
referencestring

Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_core
payer_ip_addressstring

For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

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.

incomplete_fieldsarray

An array of fields which are missing and is required to set up the mandate.

3 properties
fieldstring

The root resource.

messagestring

A localised error message

request_pointerstring

The path to the field e.g. "/payer_authorisations/customer/city"

linksobject

IDs of the created resources. Available after the Payer Authorisation is completed.

3 properties
customerstring

Unique identifier, beginning with "CU".

bank_accountstring

Unique identifier, beginning with "BA".

mandatestring

Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.

statusstring

One of:

  • created: The PayerAuthorisation has been created, and not been confirmed yet
  • submitted: The payer information has been submitted
  • confirmed: PayerAuthorisation is confirmed and resources are ready to be created
  • completed: The PayerAuthorisation has been completed and customer, bank_account and mandate has been created
  • failed: The PayerAuthorisation has failed and customer, bank_account and mandate is not created
createdsubmittedconfirmedcompletedfailed
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 a Payer Authorisation#

POST/payer_authorisations

Creates a Payer Authorisation. The resource is saved to the database even if incomplete. An empty array of incomplete_fields means that the resource is valid. The ID of the resource is used for the other actions. This endpoint has been designed this way so you do not need to save any payer data on your servers or the browser while still being able to implement a progressive solution, such as a multi-step form.

Deprecated: Payer Authorisation is legacy API and cannot be used by new integrators. The Billing Request API should be used for any new integrations.

POST https://api.gocardless.com/payer_authorisations HTTP/1.1
Content-Type: application/json
{
  "payer_authorisations": {
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    }
  }
}

Example response with incomplete_fields
@client.payer_authorisations.create(
  params: {
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    }
  }
)
client.payer_authorisations.create(params={
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {}
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    }
})
const payerAuthorisation = await client.payerAuthorisations.create({
  "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "branch_code": "200000",
      "account_number": "55779911",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    }
});
$client->payerAuthorisations()->create([
  "params" => ["customer" => [
      "email" => "mail@example.com",
      "given_name" => "Name",
      "family_name" => "Surname",
      "metadata" => [
        "salesforce_id" => "EFGH5678"
      ]
    ],
    "bank_account" => [
      "account_holder_name" => "Name Surname",
      "branch_code" => "200000",
      "account_number" => "55779911",
      "metadata" => []
    ],
    "mandate" => [
      "reference" => "XYZ789",
      "metadata" => []
    ]]
]);
PayerAuthorisation payerAuthorisation = client.payerAuthorisations().create()
  .withCustomerEmail("mail@example.com")
  .withCustomerGivenName("Name")
  .withCustomerFamilyName("Surname")
  .withBankAccountAccountHolderName("Name Surname")
  .withBankAccountBranchCode("200000")
  .withBankAccountAccountNumber("55779911")
  .withMandateReference("XYZ789")
  .execute();
payerAuthorisationCreateParams := gocardless.PayerAuthorisationCreateParams{
  Customer: gocardless.PayerAuthorisationCreateParamsCustomer{
    Email:      "mail@example.com",
    GivenName:  "Name",
    FamilyName: "Surname",
    Metadata:   map[string]string{"salesforce_id": "EFGH5678"},
  },
  BankAccount: gocardless.PayerAuthorisationCreateParamsBankAccount{
    AccountHolderName: "Name Surname",
    BranchCode:        "200000",
    AccountNumber:     "55779911",
  },
  Mandate: gocardless.PayerAuthorisationCreateParamsMandate{
    Reference: "XYZ789",
  },
}

payerAuthorisation, err := client.PayerAuthorisations.Create(ctx, payerAuthorisationCreateParams)
var customer = new GoCardless.Services.PayerAuthorisationCreateRequest.PayerAuthorisationCustomer()
{
  Email = "mail@example.com",
  GivenName = "Name",
  FamilyName = "Surname",
  Metadata = new Dictionary<string, string>()
};
var bankAccount = new GoCardless.Services.PayerAuthorisationCreateRequest.PayerAuthorisationBankAccount()
{
  AccountHolderName = "Name Surname",
  BranchCode = "200000",
  AccountNumber = "55779911",
  Metadata = new Dictionary<string, string>()
};
var mandate = new GoCardless.Services.PayerAuthorisationCreateRequest.PayerAuthorisationMandate()
{
  Reference = "XYZ789",
  Metadata = new Dictionary<string, string>()
};
var PayerAuthorisationRequest = new GoCardless.Services.PayerAuthorisationCreateRequest()
{
    Customer = customer,
    BankAccount = bankAccount,
    Mandate = mandate
};
var PayerAuthorisationResponse = await client.PayerAuthorisations.CreateAsync(PayerAuthorisationRequest);
GoCardless.Resources.PayerAuthorisation payerAuthorisation = PayerAuthorisationResponse.PayerAuthorisation;
Responsehttp
HTTP/1.1 201 Created
Location: /payer_authorisations/PA123
Content-Type: application/json
{
  "payer_authorisations": {
    "id": "PA123",
    "created_at": "2020-04-15T15:00:00.000Z",
    "status": "created",
    "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "account_number_ending": "11",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    },
    "links": {},
    "incomplete_fields":[
      {
        "field": "payer_authorisations",
        "message": "is required",
        "request_pointer": "/payer_authorisations/customer/address_line1"
      },
      {
        "field": "payer_authorisations",
        "message": "is required",
        "request_pointer": "/payer_authorisations/customer/city"
      },
      {
        "field": "payer_authorisations",
        "message": "is required",
        "request_pointer": "/payer_authorisations/customer/postal_code"
      }
    ]
  }
}

Example response with all properties

HTTP/1.1 201 Created
Content-Type: application/json
{
  "payer_authorisations": {
      "id": "PA123",
      "created_at": "2020-04-15T15:00:00.000Z",
      "status": "created",
      "customer": {
      "email": "mail@example.com",
      "given_name": "Name",
      "family_name": "Surname",
      "metadata": {
        "salesforce_id": "EFGH5678"
      }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "account_number_ending": "11",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    },
      "links": {},
      "incomplete_fields": []
  }
}

Example response with errors

HTTP/1.1 422 Unprocessable entity
Content-Type: application/json
{
  "error": {
      "message": "Validation failed",
      "errors": [
          {
              "field": "bank_account",
              "message": "is the wrong length (should be 8 characters)",
              "request_pointer": "/payer_authorisations/bank_account/account_number"
          },
          {
              "field": "bank_account",
              "message": "is required",
              "request_pointer": "/payer_authorisations/bank_account/branch_code"
          },
          {
              "field": "bank_account",
              "message": "is required",
              "request_pointer": "/payer_authorisations/bank_account/branch_code"
          }
      ],
      "documentation_url": "https://developer.gocardless.com/api-reference#validation_failed",
      "type": "validation_failed",
      "request_id": "5a83ff47-cfb0-4bb8-8bcd-a3bddf0118e1",
      "code": 422
  }
}
Request Body
payer_authorisationsobject
3 properties
customerobject

All details required for the creation of a Customer.

15 properties
emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

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.

country_codestring

ISO 3166-1 alpha-2 code.

localestring

An IETF Language Tag, used for both language and regional variations of our product.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

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.

bank_accountobject

All details required for the creation of a Customer Bank Account.

11 properties
account_holder_namestring

Name of the account holder, as known by the bank. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. This field is required unless the request includes a customer bank account token.

account_numberstring

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

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_number_suffixstring

Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.

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.

ibanstring

International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

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

mandateobject

All details required for the creation of a Mandate.

4 properties
referencestring

Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_core
payer_ip_addressstring

For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

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 201

Resource created successfully

payer_authorisationsobject
8 properties
idstring

Unique identifier, beginning with "PA".

created_atstring

Timestamp, recording when this Payer Authorisation was created.

customerobject

All details required for the creation of a Customer.

15 properties
emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

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.

country_codestring

ISO 3166-1 alpha-2 code.

localestring

An IETF Language Tag, used for both language and regional variations of our product.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

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.

bank_accountobject

All details required for the creation of a Customer Bank Account.

11 properties
account_holder_namestring

Name of the account holder, as known by the bank. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. This field is required unless the request includes a customer bank account token.

account_numberstring

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

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_number_suffixstring

Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.

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.

ibanstring

International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

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

mandateobject

All details required for the creation of a Mandate.

4 properties
referencestring

Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_core
payer_ip_addressstring

For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

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.

incomplete_fieldsarray

An array of fields which are missing and is required to set up the mandate.

3 properties
fieldstring

The root resource.

messagestring

A localised error message

request_pointerstring

The path to the field e.g. "/payer_authorisations/customer/city"

linksobject

IDs of the created resources. Available after the Payer Authorisation is completed.

3 properties
customerstring

Unique identifier, beginning with "CU".

bank_accountstring

Unique identifier, beginning with "BA".

mandatestring

Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.

statusstring

One of:

  • created: The PayerAuthorisation has been created, and not been confirmed yet
  • submitted: The payer information has been submitted
  • confirmed: PayerAuthorisation is confirmed and resources are ready to be created
  • completed: The PayerAuthorisation has been completed and customer, bank_account and mandate has been created
  • failed: The PayerAuthorisation has failed and customer, bank_account and mandate is not created
createdsubmittedconfirmedcompletedfailed
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

Submit a Payer Authorisation#

POST/payer_authorisations/{payer_authorisation_id}/actions/submit

Submits all the data previously pushed to this PayerAuthorisation for verification. This time, a 200 HTTP status is returned if the resource is valid and a 422 error response in case of validation errors. After it is successfully submitted, the Payer Authorisation can no longer be edited.

Deprecated: Payer Authorisation is legacy API and cannot be used by new integrators. The Billing Request API should be used for any new integrations.

Path Parameters

NameTypeDescription
payer_authorisation_idrequiredstring

The payer authorisation id

POST https://api.gocardless.com/payer_authorisations/PA123/actions/submit HTTP/1.1
@client.payer_authorisations.submit("PAU123")
client.payer_authorisations.submit("PAU123")
const payerAuthorisation = await client.payerAuthorisations.submit("PAU123");
$client->payerAuthorisations()->submit("PAU123");
PayerAuthorisation payerAuthorisation = client.payerAuthorisations().submit("PAU123").execute();
payerAuthorisation, err := client.PayerAuthorisations.Submit(ctx, "PAU123")
var payerAuthorisationResponse = await client.PayerAuthorisations.SubmitAsync("PAU123");
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "payer_authorisations": {
    "id": "PA123",
    "created_at": "2020-04-15T15:00:00.000Z",
    "status": "submitted",
    "customer": {
        "email": "mail@example.com",
        "given_name": "Name",
        "family_name": "Surname",
        "metadata": {
          "salesforce_id": "EFGH5678"
        }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "account_number_ending": "11",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    },
    "links": {},
    "incomplete_fields": []
  }
}

or

Example response with errors

HTTP/1.1 422 Unprocessable entity
Content-Type: application/json
{

  "error": {
      "message": "Validation failed",
      "errors": [
          {
              "field": "customer",
              "message": "is not valid",
              "request_pointer": "/payer_authorisations/customer/email"
          }
      ],
      "documentation_url": "https://developer.gocardless.com/api-reference#validation_failed",
      "type": "validation_failed",
      "request_id": "2f0db86c-251c-432a-a7af-b77f1a426a37",
      "code": 422
  }

}

or

Example response if the resource is already submitted

HTTP/1.1 304 Not modified
{}
Response 200

Action completed successfully

payer_authorisationsobject
8 properties
idstring

Unique identifier, beginning with "PA".

created_atstring

Timestamp, recording when this Payer Authorisation was created.

customerobject

All details required for the creation of a Customer.

15 properties
emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

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.

country_codestring

ISO 3166-1 alpha-2 code.

localestring

An IETF Language Tag, used for both language and regional variations of our product.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

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.

bank_accountobject

All details required for the creation of a Customer Bank Account.

11 properties
account_holder_namestring

Name of the account holder, as known by the bank. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. This field is required unless the request includes a customer bank account token.

account_numberstring

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

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_number_suffixstring

Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.

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.

ibanstring

International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

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

mandateobject

All details required for the creation of a Mandate.

4 properties
referencestring

Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_core
payer_ip_addressstring

For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

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.

incomplete_fieldsarray

An array of fields which are missing and is required to set up the mandate.

3 properties
fieldstring

The root resource.

messagestring

A localised error message

request_pointerstring

The path to the field e.g. "/payer_authorisations/customer/city"

linksobject

IDs of the created resources. Available after the Payer Authorisation is completed.

3 properties
customerstring

Unique identifier, beginning with "CU".

bank_accountstring

Unique identifier, beginning with "BA".

mandatestring

Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.

statusstring

One of:

  • created: The PayerAuthorisation has been created, and not been confirmed yet
  • submitted: The payer information has been submitted
  • confirmed: PayerAuthorisation is confirmed and resources are ready to be created
  • completed: The PayerAuthorisation has been completed and customer, bank_account and mandate has been created
  • failed: The PayerAuthorisation has failed and customer, bank_account and mandate is not created
createdsubmittedconfirmedcompletedfailed
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

Confirm a Payer Authorisation#

POST/payer_authorisations/{payer_authorisation_id}/actions/confirm

Confirms the Payer Authorisation, indicating that the resources are ready to be created. A Payer Authorisation cannot be confirmed if it hasn't been submitted yet.

The main use of the confirm endpoint is to enable integrators to acknowledge the end of the setup process. They might want to make the payers go through some other steps after they go through our flow or make them go through the necessary verification mechanism (upcoming feature).

Deprecated: Payer Authorisation is legacy API and cannot be used by new integrators. The Billing Request API should be used for any new integrations.

Path Parameters

NameTypeDescription
payer_authorisation_idrequiredstring

The payer authorisation id

POST https://api.gocardless.com/payer_authorisations/PA123/actions/confirm HTTP/1.1
@client.payer_authorisations.confirm("PAU123")
client.payer_authorisations.confirm("PAU123")
const payerAuthorisation = await client.payerAuthorisations.confirm("PAU123");
$client->payerAuthorisations()->confirm("PAU123");
PayerAuthorisation payerAuthorisation = client.payerAuthorisations().confirm("PAU123").execute();
payerAuthorisation, err := client.PayerAuthorisations.Confirm(ctx, "PAU123")
var payerAuthorisationResponse = await client.PayerAuthorisations.ConfirmAsync("PAU123");
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "payer_authorisations": {
    "id": "PA123",
    "created_at": "2020-04-15T15:00:00.000Z",
    "status": "confirmed",
    "customer": {
        "email": "mail@example.com",
        "given_name": "Name",
        "family_name": "Surname",
        "metadata": {
          "salesforce_id": "EFGH5678"
        }
    },
    "bank_account": {
      "account_holder_name": "Name Surname",
      "account_number_ending": "11",
      "metadata": {}
    },
    "mandate": {
      "reference": "XYZ789",
      "metadata": {}
    },
    "links": {},
    "incomplete_fields": []
  }
}

or

HTTP/1.1 422 Bad Request
Content-Type: application/json
{
  "error": {
    "message": "The Payer Authorisation needs to be submitted before confirmation",
    "errors": [
      {
        "reason": "payer_authorisation_submit_before_confirm",
        "message": "The Payer Authorisation needs to be submitted before confirmation"
      }
    ],
    "documentation_url": "https://developer.gocardless.com/api-reference#payer_authorisation_submit_before_confirm",
    "type": "invalid_state",
    "request_id": "...",
    "code": 422
  }
}
Response 200

Action completed successfully

payer_authorisationsobject
8 properties
idstring

Unique identifier, beginning with "PA".

created_atstring

Timestamp, recording when this Payer Authorisation was created.

customerobject

All details required for the creation of a Customer.

15 properties
emailstring

Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.

given_namestring

Customer's first name. Required unless a company_name is provided.

family_namestring

Customer's surname. Required unless a company_name is provided.

company_namestring

Customer's company name. Required unless a given_name and family_name are provided. For Canadian customers, the use of a company_name value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD").

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.

country_codestring

ISO 3166-1 alpha-2 code.

localestring

An IETF Language Tag, used for both language and regional variations of our product.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK).

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.

bank_accountobject

All details required for the creation of a Customer Bank Account.

11 properties
account_holder_namestring

Name of the account holder, as known by the bank. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. This field is required unless the request includes a customer bank account token.

account_numberstring

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

account_number_endingstring

The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.

account_number_suffixstring

Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.

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.

ibanstring

International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.

country_codestring

ISO 3166-1 alpha-2 code. Defaults to the country code of the iban if supplied, otherwise is required.

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

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

mandateobject

All details required for the creation of a Mandate.

4 properties
referencestring

Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported.

achautogirobacsbecsbecs_nzbetalingsservicefaster_paymentspadpay_tosepa_core
payer_ip_addressstring

For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).

Not required for creating offline mandates where authorisation_source is set to telephone or paper.

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.

incomplete_fieldsarray

An array of fields which are missing and is required to set up the mandate.

3 properties
fieldstring

The root resource.

messagestring

A localised error message

request_pointerstring

The path to the field e.g. "/payer_authorisations/customer/city"

linksobject

IDs of the created resources. Available after the Payer Authorisation is completed.

3 properties
customerstring

Unique identifier, beginning with "CU".

bank_accountstring

Unique identifier, beginning with "BA".

mandatestring

Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.

statusstring

One of:

  • created: The PayerAuthorisation has been created, and not been confirmed yet
  • submitted: The payer information has been submitted
  • confirmed: PayerAuthorisation is confirmed and resources are ready to be created
  • completed: The PayerAuthorisation has been completed and customer, bank_account and mandate has been created
  • failed: The PayerAuthorisation has failed and customer, bank_account and mandate is not created
createdsubmittedconfirmedcompletedfailed
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