Bring your own - Consent Journey

Occasionally it is necessary to integrate the consent flow into an existing application. This can be helpful when you are migrating from an existing provider, or working with providers in different regions and want to provide your users with a consistent user experience. In this case we provide access to the relevant API to retrive the necessary data to perform the connection journey. You are required to deliver for the mandatory aspects defined above. When the ‘Bring your own consent’ option is used, the new application will be required to be reviewed before it can be launched.

Find or create user #

Find or create a user. The ID associated with this users is used in the next step.

Does the user exist? You can check at the /user endpoint.

GET /partner/{partnerId}/app/{appId}/users

curl --location 'https://api.wych.io/v3/partner/{partnerId}/app/{appId}/users' \
--header 'x-api-key: apixxxxxkey' \
--header 'Authorization: Bearer eyJxxxxg2Q'

[
    {
        "id": "c6xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx92",
        "email": "test-user@example.com"
    },
    {
        "id": "00xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx0d",
        "email": "another-user@example.com"
    }
]

If they don’t exist, you can direct them to your dedicated connection URL or create them by POST-ing the users details to the /user endpoint.

POST /partner/{partnerId}/app/{appId}/user

curl --location 'https://api.wych.io/v3/partner/{partnerId}/app/{appId}/user' \
--header 'x-api-key: apixxxxxkey' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJxxxxg2Q'
--data-raw '{
    "email": "a.new-user@example.com"
}'

{
    "id": "a1xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxb2",
    "email": "a.new-user@example.com"
}'

Set the user in context #

You can now set the user in context. The remaining commands will be performed with a user context token.

This is a token exchange, swapping your service token for a token locked to the customer whose details you wish to extract. Set the userId in the URL path /user/{userId}/token. You will be returned an auth_token which must be used for the following user context queries.

POST /partner/{partnerId}/app/{appId}/user/{userId}/token

curl --location 'https://api.wych.io/v3/partner/{partnerId}/app/{appId}/user/{userId}/token' \
--header 'x-api-key: apixxxxxkey' \
--header 'Authorization: Bearer eyJxxxxg2Q'

{
    "access_token": "eyXXXXXXzA",
    ...
}

Get available data holders #

Retrieve the list of data holders to present to the user. This can be cached.

GET /data-holders

curl --location 'https://api.wych.io/v3/data-holders' \
--header 'x-api-key: apixxxxxkey' \
--header 'Authorization: Bearer eyJxxxxg2Q'

[
    {
        "id": "37xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx86",
        "externalId": "AU_CDS",
        "name": "Australian Consumer Data Standards",
        "dataHolders": [
            {
                "id": "1cxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx61",
                "name": "QBANK",
                "country": "AU",
                "connectable": true,
                "enabled": true,
                "logoUri": "https://www.qbank.com.au/media/logo/qbank-logo.svg",
                "externalId": "28xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx20",
                "permissions": {}
            },
            ...
    }
]

Create the connection #

Create a connection passing the user id, dataholder id and valid authorisation-scopes, as a minimumn openid must be included.

POST /connection

curl --location 'https://api.wych.io/v3/connection' \
--header 'x-api-key: apixxxxxkey' \
--header 'Authorization: Bearer eyJxxxxg2Q' \
--header 'Content-Type: application/json' \
--data '{
    "app": {{app_name}},
    "dataholder": "37xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx86", 
    "user": "a1xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxb2",
    "scopes": [
        "openid",
        "common:customer.basic:read",
        "common:customer.detail:read",
        "bank:accounts.basic:read",
        "bank:accounts.detail:read",
        "bank:transactions:read",
        "bank:regular_payments:read",
        "bank:payees:read"
    ]
}'

{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Authorise to request PAR #

Confirm the end-user has authorised you to access their data scopes, for a specified period.

POST /connection/{connectionId}/authorize

curl --location 'https://api.wych.io/v3/connection/{connectionId}/authorize' \
--header 'x-api-key: apixxxxxkey' \
--header 'Authorization: Bearer eyJxxxxg2Q'

{
    "uri": "string"
}

You can now redirect the user to the URI returned by the /authorize call. The user will be brought to their bank or energy company where they consent to your access. The bank will redirect back to Wych, to activate the connection, and begin extraction before Wych redirects back to your service with confirmation. You may then begin the data extraction process.

#