Sandbox API Getting Started Guide

Introduction

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.

Guide

1. Register new customer

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...."
}

2. Get a list of account providers

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'

3. Get data clusters for chosen account 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'

4. Begin the authentication process

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):

  • 111111111111
  • 222222222222
  • 333333333333

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.

6. Optionally add more accounts

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.

7. View all consents for a customer

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'

8. Get customer data

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.

8.1 Get accounts for a specific provider

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'

8.2 Get balances for a specific account:

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'

8.3 Get transactions for a specific account (including categorisation metadata)

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'

8.4 Get all transactions for all 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/transactions'