GoCardlessDeveloper Docs
Create a sandbox account

Redirect Flow

View as Markdown

Deprecated: Redirect Flows are legacy APIs and cannot be used by new integrators. The Billing Request flow API should be used for your payment flows.

Redirect flows enable you to use GoCardless' hosted payment pages to set up mandates with your customers. These pages are fully compliant and have been translated into Danish, Dutch, French, German, Italian, Norwegian, Portuguese, Slovak, Spanish and Swedish.

The overall flow is:

  1. You create a redirect flow for your customer, and redirect them to the returned redirect url, e.g. https://pay.gocardless.com/flow/RE123.

  2. Your customer supplies their name, email, address, and bank account details, and submits the form. This securely stores their details, and redirects them back to your success_redirect_url with redirect_flow_id=RE123 in the querystring.

  3. You complete the redirect flow, which creates a customer, customer bank account, and mandate, and returns the ID of the mandate. You may wish to create a subscription or payment at this point.

Once you have completed the redirect flow via the API, you should display a confirmation page to your customer, confirming that their Direct Debit has been set up. You can build your own page, or redirect to the one we provide in the confirmation_url attribute of the redirect flow.

Redirect flows expire 30 minutes after they are first created. You cannot complete an expired redirect flow. For an integrator this is shorter and they will expire after 10 minutes.

Create a redirect flow#

POST/redirect_flows

Creates a redirect flow object which can then be used to redirect your customer to the GoCardless hosted payment pages.

Deprecated: Redirect Flows are legacy APIs and cannot be used by new integrators. The Billing Request flow API should be used for your payment flows.

POST https://api.gocardless.com/redirect_flows HTTP/1.1
Content-Type: application/json
{
  "redirect_flows": {
    "description": "Wine boxes",
    "session_token": "SESS_wSs0uGYMISxzqOBq",
    "success_redirect_url": "https://example.com/pay/confirm",
    "prefilled_customer": {
      "given_name": "Frank",
      "family_name": "Osborne",
      "email": "frank.osborne@acmeplc.com"
    },
    "links": {
         "creditor": "CR123"
     }
  }
}
@client.redirect_flows.create(
  params: {
    description: "Team membership",
    session_token: "my_unique_tracking_id",
    success_redirect_url: "https://example.com/pay/confirm",
    prefilled_customer: {
      given_name: "Frank",
      family_name: "Osborne",
      email: "frank.osborne@acmeplc.com"
    }
  }
)
client.redirect_flows.create(params={
    "description": "Wine boxes",
    "session_token": "SESS_wSs0uGYMISxzqOBq",
    "success_redirect_url": "https://example.com/pay/confirm",
    "prefilled_customer": {
        "given_name": "Frank",
        "family_name": "Osborne",
        "email": "frank.osborne@acmeplc.com"
    }
})
const redirectFlow = await client.redirectFlows.create({
  description: "Wine boxes",
  session_token: "SESS_wSs0uGYMISxzqOBq",
  success_redirect_url: "https://example.com/pay/confirm",
  prefilled_customer: {
    given_name: "Frank",
    family_name: "Osborne",
    email: "frank.osborne@acmeplc.com"
  }
});
$client->redirectFlows()->create([
  "params" => ["description" => "Wine boxes",
               "session_token" => "SESS_wSs0uGYMISxzqOBq",
               "success_redirect_url" => "https://example.com/pay/confirm",
               "prefilled_customer" => [
                 "given_name" => "Frank",
                 "family_name" => "Osborne",
                 "email" => "frank.osborne@acmeplc.com"
               ]]
]);
RedirectFlow redirectFlow = client.redirectFlows().create()
  .withDescription("Wine boxes")
  .withSessionToken("SESS_wSs0uGYMISxzqOBq")
  .withSuccessRedirectUrl("https://example.com/pay/confirm")
  .withPrefilledCustomerGivenName("Frank")
  .withPrefilledCustomerFamilyName("Osborne")
  .withPrefilledCustomerEmail("frank.osborne@acmeplc.com")
  .execute();
redirectFlowCreateParams := gocardless.RedirectFlowCreateParams{
  Description: "Cider Barrels",
  Links: &gocardless.RedirectFlowCreateParamsLinks{
    Creditor: "CR00006A7FRJA5",
  },
  PrefilledCustomer: &gocardless.RedirectFlowCreateParamsPrefilledCustomer{
    AddressLine1: "338-346 Goswell Road",
    City:         "London",
    GivenName:    "Tim",
    FamilyName:   "Rogers",
    Email:        "tim@gocardless.com",
    PostalCode:   "EC1V 7LQ",
  },
  Scheme:             "bacs",
  SessionToken:       "dummy_session_token",
  SuccessRedirectUrl: "https://developer.gocardless.com/example-redirect-uri/",
}

redirectFlow, err := client.RedirectFlows.Create(ctx, redirectFlowCreateParams)
var prefilledCustomer = new GoCardless.Services.RedirectFlowCreateRequest.RedirectFlowPrefilledCustomer()
{
    AddressLine1 = "338 Goswell Road",
    Email = "api@gocardless.com",
    GivenName = "Bobby",
    FamilyName = "Tables"
};

var redirectFlowRequest = new GoCardless.Services.RedirectFlowCreateRequest()
{
    Description = "Gold package",
    SessionToken = "SESS_wSs0uGYMISxzqOBq",
    SuccessRedirectUrl = "https://example.com/pay/confirm",
    PrefilledCustomer = prefilledCustomer
};

var redirectFlowResponse = await client.RedirectFlows.CreateAsync(redirectFlowRequest);
GoCardless.Resources.RedirectFlow redirectFlow = redirectFlowResponse.RedirectFlow;

Console.WriteLine(redirectFlow.RedirectUrl);
Responsehttp
HTTP/1.1 201 Created
Location: /redirect_flows/RE123
Content-Type: application/json
{
  "redirect_flows": {
    "id": "RE123",
    "description": "Wine boxes",
    "session_token": "SESS_wSs0uGYMISxzqOBq",
    "scheme": null,
    "success_redirect_url": "https://example.com/pay/confirm",
    "redirect_url": "http://pay.gocardless.com/flow/RE123",
    "created_at": "2014-10-22T13:10:06.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}
Request Body
redirect_flowsobject
8 properties
descriptionstring

A description of the item the customer is paying for. This will be shown on the hosted payment pages.

session_tokenstring

The customer's session ID must be provided when the redirect flow is set up and again when it is completed. This allows integrators to ensure that the user who was originally sent to the GoCardless payment pages is the one who has completed them.

schemestring

The Direct Debit scheme of the mandate. If specified, the payment pages will only allow the set-up of a mandate for the specified scheme. It is recommended that you leave this blank so the most appropriate scheme is picked based on the customer's bank account.

achautogirobacsbecsbecs_nzbetalingsservicepadsepa_core
success_redirect_urlstring

The URL to redirect to upon successful mandate setup. You must use a URL beginning https in the live environment.

prefilled_customerobject

Customer information used to prefill the payment page so your customer doesn't have to re-type details you already hold about them. It will be stored unvalidated and the customer will be able to review and amend it before completing the form.

15 properties
emailstring

Customer's email address.

given_namestring

Customer's first name.

family_namestring

Customer's surname.

company_namestring

Customer's company name. Company name should only be provided if given_name and family_name are null.

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.

postal_codestring

The customer's postal code.

country_codestring
languagestring

ISO 639-1 code.

phone_numberstring

For New Zealand customers only.

swedish_identity_numberstring

For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer.

danish_identity_numberstring

For Danish customers only. The civic/company number (CPR or CVR) of the customer.

prefilled_bank_accountobject

Bank account information used to prefill the payment page so your customer doesn't have to re-type details you already hold about them. It will be stored unvalidated and the customer will be able to review and amend it before completing the form.

1 properties
account_typestring

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

savingschecking
linksobject
1 properties
creditorstring

The creditor for whom the mandate will be created. The name of the creditor will be displayed on the payment page. Required if your account manages multiple creditors.

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. Note: This should not be used for storing PII data.

Response 201

Resource created successfully

redirect_flowsobject
11 properties
idstring

Unique identifier, beginning with "RE".

descriptionstring

A description of the item the customer is paying for. This will be shown on the hosted payment pages.

session_tokenstring

The customer's session ID must be provided when the redirect flow is set up and again when it is completed. This allows integrators to ensure that the user who was originally sent to the GoCardless payment pages is the one who has completed them.

schemestring

The Direct Debit scheme of the mandate. If specified, the payment pages will only allow the set-up of a mandate for the specified scheme. It is recommended that you leave this blank so the most appropriate scheme is picked based on the customer's bank account.

achautogirobacsbecsbecs_nzbetalingsservicepadsepa_core
success_redirect_urlstring

The URL to redirect to upon successful mandate setup. You must use a URL beginning https in the live environment.

confirmation_urlstring

The URL of a confirmation page, which you may optionally redirect the customer to rather than use your own page, that confirms in their chosen language that their Direct Debit has been set up successfully. Only returned once the customer has set up their mandate via the payment pages and the redirect flow has been completed, and only available for 15 minutes from when you complete the redirect flow. The structure of this URL may change at any time, so you should read it directly from the API response.

redirect_urlstring

The URL of the hosted payment pages for this redirect flow. This is the URL you should redirect your customer to.

created_atstring

Fixed timestamp, recording when this resource was created.

linksobject
5 properties
creditorstring

The creditor for whom the mandate will be created. The name of the creditor will be displayed on the payment page.

mandatestring

ID of mandate created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed.

customerstring

ID of customer created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed.

customer_bank_accountstring

ID of customer bank account created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed.

billing_requeststring

ID of billing request that a redirect flow can create.
Note: The redirect flow will only create a billing request in the event the redirect flow is eligible to send the payer down this new and improved flow

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. Note: This should not be used for storing PII data.

mandate_referencestring

Mandate reference generated by GoCardless or submitted by an integrator.

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

Get a single redirect flow#

GET/redirect_flows/{redirect_flow_id}

Returns all details about a single redirect flow

Deprecated: Redirect Flows are legacy APIs and cannot be used by new integrators. The Billing Request flow API should be used for your payment flows.

Path Parameters

NameTypeDescription
redirect_flow_idrequiredstring

The redirect flow id

GET https://api.gocardless.com/redirect_flows/RE123 HTTP/1.1
@client.redirect_flows.get("RE123")
client.redirect_flows.get("RE123")
const redirectFlow = await client.redirectFlows.find("RE123");
$client->redirectFlows()->get("RE123");
RedirectFlow redirectFlow = client.redirectFlows().get("RE123").execute();
redirectFlow, err := client.RedirectFlows.Get(ctx, "RE123")
var redirectFlowResponse = await client.RedirectFlows.GetAsync("RE123");
GoCardless.Resources.RedirectFlow redirectFlow = redirectFlowResponse.RedirectFlow;
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "redirect_flows": {
    "id": "RE123",
    "description": "Wine boxes",
    "session_token": "SESS_wSs0uGYMISxzqOBq",
    "scheme": null,
    "success_redirect_url": "https://example.com/pay/confirm",
    "redirect_url": "http://pay.gocardless.com/flow/RE123",
    "created_at": "2014-10-22T13:10:06.000Z",
    "links": {
      "creditor": "CR123"
    }
  }
}
Response 200

Successful response

redirect_flowsobject
11 properties
idstring

Unique identifier, beginning with "RE".

descriptionstring

A description of the item the customer is paying for. This will be shown on the hosted payment pages.

session_tokenstring

The customer's session ID must be provided when the redirect flow is set up and again when it is completed. This allows integrators to ensure that the user who was originally sent to the GoCardless payment pages is the one who has completed them.

schemestring

The Direct Debit scheme of the mandate. If specified, the payment pages will only allow the set-up of a mandate for the specified scheme. It is recommended that you leave this blank so the most appropriate scheme is picked based on the customer's bank account.

achautogirobacsbecsbecs_nzbetalingsservicepadsepa_core
success_redirect_urlstring

The URL to redirect to upon successful mandate setup. You must use a URL beginning https in the live environment.

confirmation_urlstring

The URL of a confirmation page, which you may optionally redirect the customer to rather than use your own page, that confirms in their chosen language that their Direct Debit has been set up successfully. Only returned once the customer has set up their mandate via the payment pages and the redirect flow has been completed, and only available for 15 minutes from when you complete the redirect flow. The structure of this URL may change at any time, so you should read it directly from the API response.

redirect_urlstring

The URL of the hosted payment pages for this redirect flow. This is the URL you should redirect your customer to.

created_atstring

Fixed timestamp, recording when this resource was created.

linksobject
5 properties
creditorstring

The creditor for whom the mandate will be created. The name of the creditor will be displayed on the payment page.

mandatestring

ID of mandate created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed.

customerstring

ID of customer created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed.

customer_bank_accountstring

ID of customer bank account created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed.

billing_requeststring

ID of billing request that a redirect flow can create.
Note: The redirect flow will only create a billing request in the event the redirect flow is eligible to send the payer down this new and improved flow

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. Note: This should not be used for storing PII data.

mandate_referencestring

Mandate reference generated by GoCardless or submitted by an integrator.

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

Complete a redirect flow#

POST/redirect_flows/{redirect_flow_id}/actions/complete

This creates a customer, customer bank account, and mandate using the details supplied by your customer and returns the ID of the created mandate.

This will return a redirect_flow_incomplete error if your customer has not yet been redirected back to your site, and a redirect_flow_already_completed error if your integration has already completed this flow. It will return a bad_request error if the session_token differs to the one supplied when the redirect flow was created.

Deprecated: Redirect Flows are legacy APIs and cannot be used by new integrators. The Billing Request flow API should be used for your payment flows.

Path Parameters

NameTypeDescription
redirect_flow_idrequiredstring

The redirect flow id

POST https://api.gocardless.com/redirect_flows/RE123/actions/complete HTTP/1.1
Content-Type: application/json
{
  "data": {
    "session_token": "SESS_wSs0uGYMISxzqOBq"
  }
}
@client.redirect_flows.complete(
  "RE123",
  params: {
    session_token: "my_unique_tracking_id"
  }
)
client.redirect_flows.complete("RE123", params={
  "session_token": "SESS_wSs0uGYMISxzqOBq"
})
const redirectFlowResponse = await client.redirectFlows.complete(
  "RE123",
  {
    session_token: "SESS_wSs0uGYMISxzqOBq"
  }
)
$client->redirectFlows()->complete("RE123", [
  "params" => ["session_token" => "SESS_wSs0uGYMISxzqOBq"]
]);
client.redirectFlows().complete("RE123")
  .withSessionToken("SESS_wSs0uGYMISxzqOBq")
  .execute();
redirectFlowCompleteParams := gocardless.RedirectFlowCompleteParams{
  SessionToken: "dummy_session_token",
}

redirectFlow, err := client.RedirectFlows.Complete(ctx, "RE0003QNP5DE2101R80QZHJ2X12P93Q4", redirectFlowCompleteParams)
var redirectFlowRequest = new GoCardless.Services.RedirectFlowCompleteRequest()
{
    SessionToken = "SESS_wSs0uGYMISxzqOBq"
};

var redirectFlowResponse = await client.RedirectFlows.CompleteAsync("RE123", redirectFlowRequest);
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "redirect_flows": {
    "id": "RE123",
    "description": "Wine boxes",
    "session_token": "SESS_wSs0uGYMISxzqOBq",
    "scheme": null,
    "success_redirect_url": "https://example.com/pay/confirm",
    "confirmation_url": "https://pay.gocardless.com/flow/RE123/success",
    "created_at": "2014-10-22T13:10:06.000Z",
    "mandate_reference": "AB1YZ",
    "links": {
      "creditor": "CR123",
      "mandate": "MD123",
      "customer": "CU123",
      "customer_bank_account": "BA123"
    }
  }
}
Request Body
redirect_flowsobject
1 properties
session_tokenstring

The customer's session ID must be provided when the redirect flow is set up and again when it is completed. This allows integrators to ensure that the user who was originally sent to the GoCardless payment pages is the one who has completed them.

Response 200

Action completed successfully

redirect_flowsobject
11 properties
idstring

Unique identifier, beginning with "RE".

descriptionstring

A description of the item the customer is paying for. This will be shown on the hosted payment pages.

session_tokenstring

The customer's session ID must be provided when the redirect flow is set up and again when it is completed. This allows integrators to ensure that the user who was originally sent to the GoCardless payment pages is the one who has completed them.

schemestring

The Direct Debit scheme of the mandate. If specified, the payment pages will only allow the set-up of a mandate for the specified scheme. It is recommended that you leave this blank so the most appropriate scheme is picked based on the customer's bank account.

achautogirobacsbecsbecs_nzbetalingsservicepadsepa_core
success_redirect_urlstring

The URL to redirect to upon successful mandate setup. You must use a URL beginning https in the live environment.

confirmation_urlstring

The URL of a confirmation page, which you may optionally redirect the customer to rather than use your own page, that confirms in their chosen language that their Direct Debit has been set up successfully. Only returned once the customer has set up their mandate via the payment pages and the redirect flow has been completed, and only available for 15 minutes from when you complete the redirect flow. The structure of this URL may change at any time, so you should read it directly from the API response.

redirect_urlstring

The URL of the hosted payment pages for this redirect flow. This is the URL you should redirect your customer to.

created_atstring

Fixed timestamp, recording when this resource was created.

linksobject
5 properties
creditorstring

The creditor for whom the mandate will be created. The name of the creditor will be displayed on the payment page.

mandatestring

ID of mandate created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed.

customerstring

ID of customer created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed.

customer_bank_accountstring

ID of customer bank account created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed.

billing_requeststring

ID of billing request that a redirect flow can create.
Note: The redirect flow will only create a billing request in the event the redirect flow is eligible to send the payer down this new and improved flow

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. Note: This should not be used for storing PII data.

mandate_referencestring

Mandate reference generated by GoCardless or submitted by an integrator.

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