This guide details the steps required to register a customer, get consent to access their account(s), and then examples of some data requests.
The full API reference is here.
Note that the data in the sandbox is not particularly realistic, so is really just intended for integration testing. However, the sandbox data can be customised, so if you want to add realistic customer account data, then let us know and we can provide a yaml format which you’d need to fill out with your data.
The first step is to register a customer on the Ducit platform. You provide the email address, first and last names in the POST data.
curl -X POST \
--key {YOUR_KEY_FILE} \
--cert {YOUR_PEM_FILE} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-fapi-interaction-id: 1f995825-1e50-45ee-8e40-6fa1defcc95c' \
-d '{"email": "john.smith@ducit.ai", "first_name": "John", "last_name": "Smith"}' \
'https://sandbox-services.ducit.ai/v1.0/api/private/open-banking/user'
This returns an access token that will be used to authenticate API calls for this customer.
{
"user_id":"860953a2-4644-4d60-83de-b5e3afb56720",
"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...",
"refresh_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...."
}
This list would be presented to a customer to allow them to add their account(s). Note that in the sandbox environment only the natwest and rbs sandboxes are available.
curl -X GET \
--key {YOUR_KEY_FILE} \
--cert {YOUR_PEM_FILE} \
-H "Accept: application/json" \
'https://sandbox-services.ducit.ai/v1.0/api/private/open-banking/provider'
Once an account provider is chosen, get a list of data clusters for that account provider. A data cluster is an Open Banking term for a description of what information a customer will be consenting to share. This information should be presented to the customer before they agree to authenticate.
The example below fetches the data clusters for natwest:
curl -X GET \
--key {YOUR_KEY_FILE} \
--cert {YOUR_PEM_FILE} \
-H "Accept: application/json" \
'https://sandbox-services.ducit.ai/v1.0/api/private/open-banking/provider/natwest/datacluster'
This call initiates the authentication process with the chosen account provider. You must include the access token obtained previously in the Authorization header.
If you are integrating in a web environment, you must also provide a redirect uri that the user agent will be redirected to once authentication is complete. The uri does not have to exist for testing, but it does have to be registered with the Ducit platform. For testing you can use https://sandbox-demo.ducit.ai/authcallback.
If you are integrating in an app environment, then you do not need to provide the redirect uri as it will be necessary to intercept the callback uri from the bank using site association and perform the code exchange manually to complete the auth process. This is out of scope for this doc.
curl -X POST \
--key {YOUR_KEY_FILE} \
--cert {YOUR_PEM_FILE} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...' \
'https://sandbox-services.ducit.ai/v1.0/api/private/open-banking/consent?provider_id=natwest&managed=false&correlation_id=592cc50d-589d-4b03-b4ee-891ef1dee02d&redirect_uri=https://sandbox-demo.ducit.ai/authcallback
This returns a uri to which the customer’s browser should be redirected. Paste this into a browser to test.
{
"redirectUri":"https://api.natwest.useinfinite.io/authorize?response_type=code%20id_token&client_id=Qrn-UPOhhu0Ike-a7mg14NAr5my7O81BcXGnxIP5l0k%3D&state=8149b79b-ea1a-4126-a56b-100ceef9aa21&nonce=e8bde6b7-ec26-42d7-87e8-2aad63d8e474&scope=openid%20accounts&request=eyJraWQiOiJ1UDVrZHdJVEdQMmpFTmNBdEhVZXFwN1RFMkUiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJodHRwczpcL1wvYXBpLm5hdHdlc3QudXNlaW5maW5pdGUuaW8iLCJzY29wZSI6Im9wZW5pZCBhY2NvdW50cyIsImNsYWltcyI6eyJpZF90b2tlbiI6eyJhY3IiOnsidmFsdWUiOiJ1cm46b3BlbmJhbmtpbmc6cHNkMjpzY2EiLCJlc3NlbnRpYWwiOnRydWV9LCJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiJkZTc4NGFkZi1lYTRkLTQzYTQtOGNkNy05M2FmNzFkNjZhMjMiLCJlc3NlbnRpYWwiOnRydWV9fSwidXNlcmluZm8iOnsib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoiZGU3ODRhZGYtZWE0ZC00M2E0LThjZDctOTNhZjcxZDY2YTIzIiwiZXNzZW50aWFsIjp0cnVlfX19LCJpc3MiOiJRcm4tVVBPaGh1MElrZS1hN21nMTROQXI1bXk3TzgxQmNYR254SVA1bDBrPSIsInJlc3BvbnNlX3R5cGUiOiJjb2RlIGlkX3Rva2VuIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6XC9cL3NhbmRib3gtc2VydmljZXMuZHVjaXQuYWlcL3YxLjBcL3dlYlwvYjYyY2JjMDMtMjFjNS00YTQ3LWI2ZTAtMWE5ZGI2YzliNDcxXC9hY2NvdW50cmVxdWVzdHNcL2F1dGgiLCJzdGF0ZSI6IjgxNDliNzliLWVhMWEtNDEyNi1hNTZiLTEwMGNlZWY5YWEyMSIsImV4cCI6MTU4ODE2MTA2Miwibm9uY2UiOiJlOGJkZTZiNy1lYzI2LTQyZDctODdlOC0yYWFkNjNkOGU0NzQiLCJpYXQiOjE1ODgxNjA0NjIsImNsaWVudF9pZCI6IlFybi1VUE9oaHUwSWtlLWE3bWcxNE5BcjVteTdPODFCY1hHbnhJUDVsMGs9IiwianRpIjoiMGY3NmUzYzYtZmE0OS00YzQzLWFmNTgtYmM3NGQ5NDVmNDQ5In0.dGngF0KTll0jUD0VCkd0p7pcwjaJUsSEIX6hrTibVBO5hOJBO6LwPvH_KfsBG4vGW0s9wIAvX6LBCzfstmp6ugcDfVFYIlNdMPbEaWJ9e5pVKUH4K61mtNtylqn1Mv4qiS6kHshQ5KJFzKMnleJNE3KIruQxS-sJE7rt2SP5b9H77LpTAOg-eNbij8AxfB9fhvQQIEmbnrZoA8mZL0-xZQgGoeUNTWv9uoZ_5iydDg3hPoETMZYCFRKDTm9v6yZ-aTzq6-TzitdQxt43YjBkb_RCq3ca8--wvgpdHsb8FmQt8uNza3xfWCBWZ9hH5qo8L7n0LLgPRon_mNdWXC-b9Q&redirect_uri=https://sandbox-services.ducit.ai/v1.0/web/b62cbc03-21c5-4a47-b6e0-1a9db6c9b471/accountrequests/auth",
"state":"8149b79b-ea1a-4126-a56b-100ceef9aa21"
}
The customer will be taken through the provider’s authentication flow. For sandbox you can use the following customer IDs (for both natwest and rbs):
Note when asked to enter the passcode and password, just enter the same digits as the requested positions. E.g. if it asks for the third digit, enter 3.
The customer will then get to pick the accounts they want to share. Once this is done they will be redirected back to the redirect_uri specified in the consent call:
https://sandbox-demo.ducit.ai/authcallback?correlation_id=592cc50d-589d-4b03-b4ee-891ef1dee02d
The correlation_id is provided to link this back to the original call.
Simply repeat steps 2 to 5 to add more accounts. Note that if you add the same provider twice for a customer the previous consent will be overwritten with the new one. I.e. it’s only possible for a customer to add one set of accounts with a particular provider.
This endpoint will show all the accounts that a customer is currently sharing along with the time remaining for the consent (default is 90 days). You can use this endpoint to manage a customer’s consent. Check out the Consent section in the api reference for more details.
curl -X GET \
--key {YOUR_KEY_FILE} \
--cert {YOUR_PEM_FILE} \
-H 'Accept: application/json' \
-H 'x-fapi-interaction-id: 1f995825-1e50-45ee-8e40-6fa1defcc95c' \
-H 'x-fapi-customer-ip-address: 127.0.0.1' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI1OTJjYzUwZC01ODlkLTRiMDM...' \
'https://sandbox-services.ducit.ai/v1.0/api/private/open-banking/consent'
You can now retrieve data for a customer. Some example calls are shown below. See the API reference for a full list of available endpoints.
curl -X GET \
--key {YOUR_KEY_FILE} \
--cert {YOUR_PEM_FILE} \
-H 'Accept: application/json' \
-H 'x-fapi-interaction-id: 1f995825-1e50-45ee-8e40-6fa1defcc95c' \
-H 'x-fapi-customer-ip-address: 127.0.0.1' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI1OTJjYzUwZC01ODlkLTRiMDM...' \
'https://sandbox-services.ducit.ai/v1.0/api/private/open-banking/aisp/natwest/accounts'
curl -X GET \
--key {YOUR_KEY_FILE} \
--cert {YOUR_PEM_FILE} \
-H 'Accept: application/json' \
-H 'x-fapi-interaction-id: 1f995825-1e50-45ee-8e40-6fa1defcc95c' \
-H 'x-fapi-customer-ip-address: 127.0.0.1' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI1OTJjYzUwZC01ODlkLTRiMDM...' \
'https://sandbox-services.ducit.ai/v1.0/api/private/open-banking/aisp/natwest/accounts/620e9c1b-d28d-434b-a84e-d214f7931593/balances'
curl -X GET \
--key {YOUR_KEY_FILE} \
--cert {YOUR_PEM_FILE} \
-H 'Accept: application/json' \
-H 'x-fapi-interaction-id: 1f995825-1e50-45ee-8e40-6fa1defcc95c' \
-H 'x-fapi-customer-ip-address: 127.0.0.1' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI1OTJjYzUwZC01ODlkLTRiMDM...' \
'https://sandbox-services.ducit.ai/v1.0/api/private/open-banking/aisp/natwest/accounts/620e9c1b-d28d-434b-a84e-d214f7931593/transactions'
curl -X GET \
--key {YOUR_KEY_FILE} \
--cert {YOUR_PEM_FILE} \
-H 'Accept: application/json' \
-H 'x-fapi-interaction-id: 1f995825-1e50-45ee-8e40-6fa1defcc95c' \
-H 'x-fapi-customer-ip-address: 127.0.0.1' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI1OTJjYzUwZC01ODlkLTRiMDM...' \
'https://sandbox-services.ducit.ai/v1.0/api/private/open-banking/aisp/transactions'