Bank Authorisation

View as Markdown

Bank Authorisations can be used to authorise Billing Requests. Authorisations are created against a specific bank, usually the bank that provides the payer's account.

Creation of Bank Authorisations is only permitted from GoCardless hosted UIs (see Billing Request Flows) to ensure we meet regulatory requirements for checkout flows.

Create a Bank Authorisation#

POST/bank_authorisations

Create a Bank Authorisation.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/bank_authorisations HTTP/1.1
Content-Type: application/json
{
  "bank_authorisations": {
    "redirect_uri": "https://my-company.com/landing",
    "links": {
      "billing_request": "BRQ123"
    }
  }
}

@client.bank_authorisations.create(
  params: {
    redirect_uri: "https://my-company.com/landing",
    links: {
        billing_request: "BRQ123"
    }
  }
)

client.bank_authorisations.create(params={
  "redirect_uri": "https://my-company.com/landing",
  "links": {
    "billing_request": "BRQ123"
  }
})

const bankAuthorisation = await client.bankAuthorisations.create({
  redirect_uri: "https://my-company.com/landing",
  links: {
    billing_request: "BRQ123"
  }
});

$client->bankAuthorisations()->create([
  "params" => [
    "redirect_uri" => "https://my-company.com/landing",
    "links" => [
      "billing_request" => "BRQ123"
    ]
  ]
]);

BankAuthorisation bankAuthorisation = client.bankAuthorisations().create()
  .withRedirectUri("https://my-company.com/landing")
  .withLinksBillingRequest("BRQ123")
  .execute();

bankAuthorisationCreateParams := gocardless.BankAuthorisationCreateParams{
  RedirectUri: "https://my-company.com/landing",
  Links: gocardless.BankAuthorisationCreateParamsLinks{
    BillingRequest: "BR123",
  },
}

bankAuthorisation, err :=  client.BankAuthorisations.Create(ctx, bankAuthorisationCreateParams)

var authorisationLinks = new GoCardless.Services.BankAuthorisationCreateRequest.BankAuthorisationLinks
{
  BillingRequest = "BRQ123"
};

var resp = await client.BankAuthorisations.CreateAsync(
  new GoCardless.Services.BankAuthorisationCreateRequest()
  {
    RedirectUri = "https://my-company.com/landing",
    Links = authorisationLinks,
  }
);

GoCardless.Resources.BankAuthorisation bankAuthorisation = resp.BankAuthorisation;

Responsehttp

HTTP/1.1 201 Created
Location: /bank_authorisations/BAU123
Content-Type: application/json
{
  "bank_authorisations": {
    "id": "BAU123",
    "url": "https://pay-staging.gocardless.com/obauth/BAU123",
    "qr_code_url": "https://pay-staging.gocardless.com/obauth/BAU123/qr_code",
    "created_at": "2021-03-25T17:26:28.305Z",
    "authorisation_type": "payment",
    "last_visited_at": null,
    "authorised_at": null,
    "expires_at": "2021-03-25T17:41:28.000Z",
    "redirect_uri": "https://my-company.com/landing",
    "links": {
      "billing_request": "BRQ123",
      "institution": "monzo"
    }
  }
}

Request Body

bank_authorisationsobject

2 properties

redirect_uristring

URL that the payer can be redirected to after authorising the payment.

On completion of bank authorisation, the query parameter of either outcome=success or outcome=failure will be appended to the redirect_uri to indicate the result of the bank authorisation. If the bank authorisation is expired, the query parameter outcome=timeout will be appended to the redirect_uri, in which case you should prompt the user to try the bank authorisation step again.

Please note: bank authorisations can still fail despite an outcome=success on the redirect_uri. It is therefore recommended to wait for the relevant bank authorisation event, such as BANK_AUTHORISATION_AUTHORISED, BANK_AUTHORISATION_DENIED, or BANK_AUTHORISATION_FAILED in order to show the correct outcome to the user.

The BillingRequestFlow ID will also be appended to the redirect_uri as query parameter id=BRF123.

Defaults to https://pay.gocardless.com/billing/static/thankyou.

linksobject

1 properties

billing_requeststring

ID of the billing request against which this authorisation was created.

Response 201

Resource created successfully

bank_authorisationsobject

10 properties

idstring

Unique identifier, beginning with "BAU".

redirect_uristring

URL that the payer can be redirected to after authorising the payment.

The BillingRequestFlow ID will also be appended to the redirect_uri as query parameter id=BRF123.

Defaults to https://pay.gocardless.com/billing/static/thankyou.

urlstring

URL for an oauth flow that will allow the user to authorise the payment

qr_code_urlstring

URL to a QR code PNG image of the bank authorisation url. This QR code can be used as an alternative to providing the url to the payer to allow them to authorise with their mobile devices.

authorisation_typestring

Type of authorisation, can be either 'mandate' or 'payment'.

mandatepayment

created_atstring

Timestamp when the flow was created

expires_atstring

Timestamp when the url will expire. Each authorisation url currently lasts for 15 minutes, but this can vary by bank.

last_visited_atstring

Fixed timestamp, recording when the authorisation URL has been visited.

authorised_atstring

Fixed timestamp, recording when the user has been authorised.

linksobject

2 properties

billing_requeststring

ID of the billing request against which this authorisation was created.

institutionstring

ID of the institution against which this authorisation was created.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

Get a Bank Authorisation#

GET/bank_authorisations/{bank_authorisation_id}

Get a single bank authorisation.

Path Parameters

Name	Type	Description
`bank_authorisation_id`required	string	The bank authorisation id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/bank_authorisations/BAU123 HTTP/1.1

@client.bank_authorisations.get("BAU123")

client.bank_authorisations.get("BAU123")

const resp = await client.bankAuthorisations.find("BAU123");

$client->bankAuthorisations()->get("BAU123");

client.bankAuthorisations().get("BAU123").execute();

bankAuthorisation, err := client.BankAuthorisations.Get(ctx, "BAU123")

var resp = await client.BankAuthorisations.GetAsync("BAU123");

Responsehttp

HTTP/1.1 200
Content-Type: application/json
{
  "bank_authorisations": {
    "id": "BAU123",
    "url": "https://pay-staging.gocardless.com/obauth/BAU123",
    "qr_code_url": "https://pay-staging.gocardless.com/obauth/BAU123/qr_code",
    "created_at": "2021-03-25T17:26:28.305Z",
    "authorisation_type": "payment",
    "last_visited_at": null,
    "authorised_at": null,
    "expires_at": "2021-03-25T17:41:28.000Z",
    "redirect_uri": "https://my-company.com/landing",
    "links": {
      "billing_request": "BRQ123",
      "institution": "monzo"
    }
  }
}

Response 200

Successful response

bank_authorisationsobject

10 properties

idstring

Unique identifier, beginning with "BAU".

redirect_uristring

URL that the payer can be redirected to after authorising the payment.

The BillingRequestFlow ID will also be appended to the redirect_uri as query parameter id=BRF123.

Defaults to https://pay.gocardless.com/billing/static/thankyou.

urlstring

URL for an oauth flow that will allow the user to authorise the payment

qr_code_urlstring

URL to a QR code PNG image of the bank authorisation url. This QR code can be used as an alternative to providing the url to the payer to allow them to authorise with their mobile devices.

authorisation_typestring

Type of authorisation, can be either 'mandate' or 'payment'.

mandatepayment

created_atstring

Timestamp when the flow was created

expires_atstring

Timestamp when the url will expire. Each authorisation url currently lasts for 15 minutes, but this can vary by bank.

last_visited_atstring

Fixed timestamp, recording when the authorisation URL has been visited.

authorised_atstring

Fixed timestamp, recording when the user has been authorised.

linksobject

2 properties

billing_requeststring

ID of the billing request against which this authorisation was created.

institutionstring

ID of the institution against which this authorisation was created.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject