---
title: "Update a Payer Authorisation"
method: PUT
path: "/payer_authorisations/{payer_authorisation_id}"
tags: ["Payer Authorisation"]
deprecated: true
---

# Update a Payer Authorisation

`PUT /payer_authorisations/{payer_authorisation_id}`

## Request

- Base URL: `https://api.gocardless.com`
- URL: `https://api.gocardless.com/payer_authorisations/{payer_authorisation_id}`
- Auth: HTTP bearer

> **Deprecated.**

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. <p class="notice"> Note that in order to update the `metadata` attribute values it must be sent completely as it overrides the previously existing values. </p>

**Deprecated:** Payer Authorisation is legacy API and cannot be used by new integrators.
The [Billing Request](https://docs.gocardless.com/docs/api-reference/billing-request) API should be used for any new integrations.

## Path parameters

- `payer_authorisation_id` string, required

## Headers

- `GoCardless-Version` string, required

## Request body

- object
  - `payer_authorisations` object
    - `customer` PayerAuthorisationCustomer, required: All details required for the creation of a [Customer](https://docs.gocardless.com/docs/api-reference/customer).
      - `email` string, nullable: Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
      - `given_name` string, nullable: Customer's first name. Required unless a `company_name` is provided.
      - `family_name` string, nullable: Customer's surname. Required unless a `company_name` is provided.
      - `company_name` string, nullable: 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_line1` string, nullable: The first line of the customer's address.
      - `address_line2` string, nullable: The second line of the customer's address.
      - `address_line3` string, nullable: The third line of the customer's address.
      - `city` string, nullable: The city of the customer's address.
      - `region` string, nullable: The customer's address region, county or department. For US customers a 2 letter [ISO3166-2:US](https://en.wikipedia.org/wiki/ISO_3166-2:US) state code is required (e.g. `CA` for California).
      - `postal_code` string, nullable: The customer's postal code.
      - `country_code` string, nullable: [ISO 3166-1 alpha-2 code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
      - `locale` string, nullable: An [IETF Language Tag](https://tools.ietf.org/html/rfc5646), used for both language and regional variations of our product.
      - `swedish_identity_number` string, nullable: 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_number` string, nullable: 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).
      - `metadata` CustomerMetadata: 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_account` PayerAuthorisationBankAccount, required: All details required for the creation of a [Customer Bank Account](https://docs.gocardless.com/docs/api-reference/customer-bank-account).
      - `account_holder_name` string: 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](https://docs.gocardless.com/docs/collect-payments/integration-types/javascript-drop-in-flow).
      - `account_number` string, nullable: Bank account number - see [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details) for more information. Alternatively you can provide an `iban`.
      - `account_number_ending` string, nullable: The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
      - `account_number_suffix` string, nullable: Account number suffix (only for bank accounts denominated in NZD) - see [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details#new-zealand) for more information.
      - `bank_code` string, nullable: Bank code - see [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details) for more information. Alternatively you can provide an `iban`.
      - `branch_code` string, nullable: Branch code - see [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details) for more information. Alternatively you can provide an `iban`.
      - `iban` string, nullable: International Bank Account Number. Alternatively you can provide [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details). IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details#sweden).
      - `country_code` string, nullable: [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Defaults to the country code of the `iban` if supplied, otherwise is required.
      - `currency` string, nullable: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.
      - `account_type` 'savings' | 'checking', nullable: Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details#united-states) for more information.
      - `bank_name` string, nullable: Name of bank, taken from the bank details.
      - `metadata` CustomerMetadata: 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.
    - `mandate` PayerAuthorisationMandate, required: All details required for the creation of a [Mandate](https://docs.gocardless.com/docs/api-reference/mandate).
      - `reference` string, nullable: Unique reference. Different schemes have different length and [character set](https://docs.gocardless.com/docs/api-reference/character-sets) requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.
      - `scheme` 'ach' | 'autogiro' | 'bacs' | 'becs' | 'becs_nz' | 'betalingsservice' | 'faster_payments' | 'pad' | 'pay_to' | 'sepa_core', nullable: A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported.
      - `payer_ip_address` string, nullable: 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.
      - `metadata` CustomerMetadata: 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

- PayerAuthorisationSingleResourceResponse
  - `payer_authorisations` PayerAuthorisation: <p class="restricted-notice"> Don't use Payer Authorisations for new integrations. It is deprecated in favour of <a href="https://docs.gocardless.com/docs/collect-payments/setting-up-mandates"> Billing Requests</a>. Use Billing Requests to build any future integrations. </p> 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: <ol> <li> Listen to <code> payer_authorisation_completed </code> <a href="https://docs.gocardless.com/docs/api-reference/webhooks"> webhook</a> (recommended)</li> <li> Poll the GET <a href="https://docs.gocardless.com/docs/api-reference/payer-authorisation#get-a-single-payer-authorisation"> endpoint</a></li> <li> Poll the GET events API <code>https://api.gocardless.com/events?payer_authorisation={id}&action=completed</code> </li> </ol> <p class="notice"> Note that the <code>create</code> and <code>update</code> endpoints behave differently than other existing <code>create</code> and <code>update</code> endpoints. The Payer Authorisation is still saved if incomplete data is provided. We return the list of incomplete data in the <code>incomplete_fields</code> along with the resources in the body of the response. The bank account details(account_number, bank_code & branch_code) must be sent together rather than splitting across different request for both <code>create</code> and <code>update</code> endpoints. <br><br> The API is designed to be flexible and allows you to collect information in multiple steps without storing any sensitive data in the browser or in your servers. </p>
    - `id` string, required: Unique identifier, beginning with "PA".
    - `created_at` string, date-time, nullable, required: [Timestamp](https://docs.gocardless.com/docs/api-reference/data-conventions#dates-and-times), recording when this Payer Authorisation was created.
    - `customer` PayerAuthorisationCustomer, required: All details required for the creation of a [Customer](https://docs.gocardless.com/docs/api-reference/customer).
      - `email` string, nullable: Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
      - `given_name` string, nullable: Customer's first name. Required unless a `company_name` is provided.
      - `family_name` string, nullable: Customer's surname. Required unless a `company_name` is provided.
      - `company_name` string, nullable: 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_line1` string, nullable: The first line of the customer's address.
      - `address_line2` string, nullable: The second line of the customer's address.
      - `address_line3` string, nullable: The third line of the customer's address.
      - `city` string, nullable: The city of the customer's address.
      - `region` string, nullable: The customer's address region, county or department. For US customers a 2 letter [ISO3166-2:US](https://en.wikipedia.org/wiki/ISO_3166-2:US) state code is required (e.g. `CA` for California).
      - `postal_code` string, nullable: The customer's postal code.
      - `country_code` string, nullable: [ISO 3166-1 alpha-2 code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
      - `locale` string, nullable: An [IETF Language Tag](https://tools.ietf.org/html/rfc5646), used for both language and regional variations of our product.
      - `swedish_identity_number` string, nullable: 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_number` string, nullable: 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).
      - `metadata` CustomerMetadata: 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_account` PayerAuthorisationBankAccount, required: All details required for the creation of a [Customer Bank Account](https://docs.gocardless.com/docs/api-reference/customer-bank-account).
      - `account_holder_name` string: 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](https://docs.gocardless.com/docs/collect-payments/integration-types/javascript-drop-in-flow).
      - `account_number` string, nullable: Bank account number - see [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details) for more information. Alternatively you can provide an `iban`.
      - `account_number_ending` string, nullable: The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
      - `account_number_suffix` string, nullable: Account number suffix (only for bank accounts denominated in NZD) - see [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details#new-zealand) for more information.
      - `bank_code` string, nullable: Bank code - see [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details) for more information. Alternatively you can provide an `iban`.
      - `branch_code` string, nullable: Branch code - see [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details) for more information. Alternatively you can provide an `iban`.
      - `iban` string, nullable: International Bank Account Number. Alternatively you can provide [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details). IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details#sweden).
      - `country_code` string, nullable: [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Defaults to the country code of the `iban` if supplied, otherwise is required.
      - `currency` string, nullable: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.
      - `account_type` 'savings' | 'checking', nullable: Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details#united-states) for more information.
      - `bank_name` string, nullable: Name of bank, taken from the bank details.
      - `metadata` CustomerMetadata: 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.
    - `mandate` PayerAuthorisationMandate, required: All details required for the creation of a [Mandate](https://docs.gocardless.com/docs/api-reference/mandate).
      - `reference` string, nullable: Unique reference. Different schemes have different length and [character set](https://docs.gocardless.com/docs/api-reference/character-sets) requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.
      - `scheme` 'ach' | 'autogiro' | 'bacs' | 'becs' | 'becs_nz' | 'betalingsservice' | 'faster_payments' | 'pad' | 'pay_to' | 'sepa_core', nullable: A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and "sepa_core" are supported.
      - `payer_ip_address` string, nullable: 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.
      - `metadata` CustomerMetadata: 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_fields` PayerAuthorisationIncompleteField[], required: An array of fields which are missing and is required to set up the mandate.
      - `field` string: The root resource.
      - `message` string: A localised error message
      - `request_pointer` string: The path to the field e.g. "/payer_authorisations/customer/city"
    - `links` PayerAuthorisationLinks, required: IDs of the created resources. Available after the Payer Authorisation is completed.
      - `customer` string: Unique identifier, beginning with "CU".
      - `bank_account` string: Unique identifier, beginning with "BA".
      - `mandate` string: Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.
    - `status` 'created' | 'submitted' | 'confirmed' | 'completed' | 'failed', required: 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

## Other responses

- `400`: Bad Request
- `401`: Unauthorised
- `404`: Not found
- `422`: Validation Error
- `500`: Internal Error

---

[API](https://skmtc.dev/gocardless/apis/gocardless-api.md) - [All operations](https://skmtc.dev/gocardless/apis/gocardless-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gocardless/apis/gocardless-api/revisions/4dd3dae45364?raw)