Tutorial: Access data using Yapily Hosted Pages

Hosted Pages is available as a Private Beta version. Please contact your Customer Success Manager if you would like to access it.

Introduction

This tutorial explains how to use Yapily Hosted Pages to access data.

Note: All requests made to the Yapily API require basic authentication.

1. Create Hosted Consent Request

Make a request to POST /hosted/consent-requests, including the institution country code, redirect URL and user ID or application User ID.

You must provide the institutionIdentifiers.institutionCountryCode field. This controls the country of the institution to access the account data.

In addition, you can optionally provide the ID of a specific institution in institutionIdentifiers.institutionId field to only allow data access from this institution. This skips the bank selection screen in the hosted flow.

You can optionally provide userSettings to set the user’s preferred language and location.

Example request:

Copy
Copied
curl --location 'https://api.yapily.com/hosted/consent-requests' \
--header 'Content-Type: application/json;charset=UTF-8' \
--header 'Accept: application/json;charset=UTF-8' \
--header 'Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=' \
--data '{
	"redirectUrl": "https://tpp-application.com/",
	"institutionIdentifiers": {
		"institutionCountryCode": "GB"
	},
	"applicationUserId": "john.doe@company.com",
	"userSettings": {
		"language": "EN",
		"location": "GB"
	}
}'

Example response:

Copy
Copied
{
	"meta": {
		"tracingId": "bffd676d6f804357b54eab07f1f41448"
	},
	"data": {
		"consentRequestId": "fd19a5f3-b5ea-4cf0-8035-7e853a264f36",
		"userId": "034b2e9c-0b16-4b60-b948-ff3c49d50741",
		"applicationUserId": "john.doe@company.com",
		"applicationId": "2e760724-289f-43ef-8bd7-d54dbf9dd5b1",
		"institutionIdentifiers": {
			"institutionCountryCode": "GB"
		},
		"userSettings": {
			"language": "EN",
			"location": "GB"
		},
		"redirectUrl": "https://tpp-application.com",
		"hostedUrl": "https://consents.yapily.com?consentRequestId=fd19a5f3-b5ea-4cf0-8035-7e853a264f36&applicationId=2e760724-289f-43ef-8bd7-d54dbf9dd5b1#authToken=eyJraWQiOiIwNmViZTQ1Yy1hYzU5LTRiM2MtOWY5NC03MDljMDM5ZTQxYWIiLCJhbGciOiJFUzI1NiJ9.eyJhdWQiOiJwcm9kdWN0aW9uIiwic3ViIjoiMmU3NjA3MjQtMjg5Zi00M2VmLThiZDctZDU0ZGJmOWRkNWIxIiwib3JnIjoiMTg0ZTNiMTktY2YyMC00OTJiLTg5NWItOGRjYTFiYjFkNWE5IiwiY29uc2VudFJlcXVlc3RJZCI6ImZkMTlhNWYzLWI1ZWEtNGNmMC04MDM1LTdlODUzYTI2NGYzNiIsImlzcyI6Imhvc3RlZC1jb25zZW50IiwidHlwIjoiQVBQTElDQVRJT04iLCJleHAiOjE3MjgwNTA0NjgsImlhdCI6MTcyODA0OTg2OCwianRpIjoiNjk5YWFiOWQtOTJkMi00NjQ3LWE1ODktMjQxOTFhMjQzZjc0In0._DigB_vpIZOr3X7uR3KZb5lPGICVx96QwPH9XqGW1UnjY8XH0iVoGHr4y2Z1030psFOIaVq_HyU1OfMU8Hbb2g",
		"createdAt": "2024-10-04T13:51:08.703Z",
		"authorisationExpiresAt": "2024-10-04T14:01:08.000Z"
	}
}

Store the hostedUrl returned in the response to use in step 2.

2. Redirect the user to the hostedUrl

Redirect the end user from your application to the Yapily Hosted Pages URL. This initiates the user journey for the account consent request.

3. End user completes the account consent flow

The end user follows the Yapily hosted screens to complete the account consent request.

A typical journey includes bank selection, redirection to their chosen bank, account consent confirmation and redirection back to your application.

See UI screens for more details.

The user will be automatically redirected to the redirectUrl specified in the initial consent request in Step 1 once the consent flow is complete. We recommend you redirect the user back to your application to create a good user experience.

The consentRequestId is returned as part of the redirectUrl. You can use this to check the status of the account consent in step 4.

4. Retrieve details of the account consent request

On an end user’s completion of the hosted pages flow, you should check the consent status to confirm the consent has initiated successfully before proceeding with any further actions.

You can retrieve details of the account consent request using GET /hosted/consent-requests/{consentRequestId} specifying the consentRequestId in the path.

Example request:

Copy
Copied
curl --location 'https://api.yapily.com/hosted/consent-requests/consentRequestId' \
--header 'Accept: application/json;charset=UTF-8' \
--header 'Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ'

Example response:

Copy
Copied
{
	"meta": {
		"tracingId": "e8cf92170a22496799ec6e8e7a4bedb3"
	},
	"data": {
		"consentRequestId": "b6c28cea-5544-46c6-ba3b-8a20adfce636",
		"consentId": "2e2848b9-a838-4759-a259-6a3915f81902",
		"userId": "034b2e9c-0b16-4b60-b948-ff3c49d50741",
		"applicationUserId": "john.doe@company.com",
		"applicationId": "2e760724-289f-43ef-8bd7-d54dbf9dd5b1",
		"institutionIdentifiers": {
			"institutionId": "modelo-sandbox",
			"institutionCountryCode": "GB"
		},
		"userSettings": {
			"language": "EN",
			"location": "GB"
		},
		"redirectUrl": "https://display-parameters.com",
		"createdAt": "2024-10-04T14:08:05.104Z",
		"authorisationExpiresAt": "2024-10-04T14:18:05.000Z",
		"status": "AUTHORIZED",
		"phases": [
			{
				"phaseName": "INITIATED",
				"phaseCreatedAt": "2024-10-04T14:08:05.104Z"
			},
			{
				"phaseName": "INSTITUTION_SUBMITTED",
				"phaseCreatedAt": "2024-10-04T14:08:11.686Z"
			},
			{
				"phaseName": "AUTHORISATION_INITIATED",
				"phaseCreatedAt": "2024-10-04T14:08:12.030Z"
			},
			{
				"phaseName": "AUTHORISATION_CREATED",
				"phaseCreatedAt": "2024-10-04T14:08:12.367Z"
			},
			{
				"phaseName": "CONSENT_POLLING_STARTED",
				"phaseCreatedAt": "2024-10-04T14:08:28.404Z"
			},
			{
				"phaseName": "CONSENT_POLLING_ENDED",
				"phaseCreatedAt": "2024-10-04T14:08:28.892Z"
			},
			{
				"phaseName": "AUTHORISED",
				"phaseCreatedAt": "2024-10-04T14:08:28.893Z"
			},
			{
				"phaseName": "FINISHED",
				"phaseCreatedAt": "2024-10-04T14:08:28.893Z"
			}
		],
		"consentToken": "eyJraWQiOiIwNmViZTQ1Yy1hYzU5LTRiM2MtOWY5NC03MDljMDM5ZTQxYWIiLCJhbGciOiJFUzI1NiJ9.eyJJTlNUSVRVVElPTiI6Im1vZGVsby1zYW5kYm94IiwiQ09OU0VOVCI6IjJlMjg0OGI5LWE4MzgtNDc1OS1hMjU5LTZhMzkxNWY4MTkwMiIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJqb2huLmRvZUBjb21wYW55LmNvbSIsIlVTRVIiOiIwMzRiMmU5Yy0wYjE2LTRiNjAtYjk0OC1mZjNjNDlkNTA3NDEifQ.OsSU5Jr7W6L-k0c3MRpX8M-ASwGyAaf-vrgbrFJD2oz4bpWm2eE-58gzd3nO50RS7zEYCUmrGt2PTkJEgagZOQ"
	}
}

4. Retrieve account informations

Retrieve account information, specifying the consentToken in the header.