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.
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:
-
You create a redirect flow for your customer, and redirect them to the returned redirect url, e.g.
https://pay.gocardless.com/flow/RE123. -
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_urlwithredirect_flow_id=RE123in the querystring. -
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#
/redirect_flowsCreates 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.
Request Body
redirect_flowsobject8 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_coresuccess_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.
savingscheckinglinksobject
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_flowsobject11 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_coresuccess_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
Bad Request
Unauthorised
Not found
Validation Error
Internal Error
Error Body
codeintegerdocumentation_urlstringerrorsarray2 properties
reasonstringmessagestringmessagestringrequest_idstringtypestringmetadataobjectlinksobjectGet a single redirect flow#
/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
| Name | Type | Description |
|---|---|---|
redirect_flow_idrequired | string | The redirect flow id |
Response 200
Successful response
redirect_flowsobject11 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_coresuccess_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
Bad Request
Unauthorised
Not found
Validation Error
Internal Error
Error Body
codeintegerdocumentation_urlstringerrorsarray2 properties
reasonstringmessagestringmessagestringrequest_idstringtypestringmetadataobjectlinksobjectComplete a redirect flow#
/redirect_flows/{redirect_flow_id}/actions/completeThis 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
| Name | Type | Description |
|---|---|---|
redirect_flow_idrequired | string | The redirect flow id |
Request Body
redirect_flowsobject1 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_flowsobject11 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_coresuccess_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
Bad Request
Unauthorised
Not found
Validation Error
Internal Error
Error Body
codeintegerdocumentation_urlstringerrorsarray2 properties
reasonstringmessagestringmessagestringrequest_idstringtypestringmetadataobjectlinksobject