Account Sharing

On this page, details of account sharing and how it works will be explained with the endpoints.

Account sharing is one of the major features of this platform, where a user can have multiple accounts at the same time shared with another user. Users can also set the type of permission the second user can have on the shared account. For example, the primary user can set the option to share the history or view card information or maybe allow the second user to personalise the shared account.

Account Sharing Process

Users must provide Contact Permission to use this feature. The contacts are sent in bulk to check if the data is associated with any account by the middleware.

Steps for the process

1. Find and select the available contact to share the account

2. Selecting the contact to share the account

3. Selecting the permissions of the account

4. Add optional message

5. Make the account-sharing request with the optional message.

Find and select the available contact to share the account

A person can have multiple accounts, which might have the person's email address or phone number associated with them. For example, One person might have an account associated with email and another account with a phone number.

The in-app contact list will be empty for first-time users as the app doesn't have any contacts imported from the device. The first step is to ask for contact permission on the app so that you can get the list of people and send them to the middleware to check for available accounts. To make a transfer request, you must choose a contact first. To find the available contacts, make a POST request using the /v1/contacts-discovery endpoint.

After hashing, the phone numbers and email addresses must be sent using the SHA256 method. A sample request body is given below:

[    
    // this is a single entry from the contact list of the device
    {
        "id": "dev123",
        "emailHash" : "da4ea0932830481fb85ca8208da7983d7e51d780ec48db49d44ec89b82da2bcc",
        "phoneNumberHash": "653eb668de2d0073a67f01770f6a272861c9976551a018f9058b198b90048787" 
    }, 
    // this is another one
    {
        "id": "dev456",
        "emailHash" : "da4ea0932830481fb85ca8208da7983d7e51d780ec48db49d44ec89b82da2bcc",
        "phoneNumberHash": "653eb668de2d0073a67f01770f6a272861c9976551a018f9058b198b90048787" 
    }
]

discoverContacts

Required scopes - transfers

POST//transfers:8080/v1/contacts-discovery

Body

application/json

body

emailHashstring

idstring

phoneNumberHashstring

Response

200201401403404

OK

Body

application/json

emailHashstring

idstring

phoneNumberHashstring

Request

JavaScriptCurl

const response = await fetch('//transfers:8080/v1/contacts-discovery', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {}
    ]),
});
const data = await response.json();

Response

[
  {
    "emailHash": "text",
    "id": "text",
    "phoneNumberHash": "text"
  }
]

The successful response will contain the list of the account with the email or phone associated with the account.

You need the contact type and details for the account-sharing request to work. For example, if the user has a contact with "[e-mail]" email associated, then the type would be "EMAIL", and the detail would be "[e-mail]".

Selecting the permissions of the account

Users can choose what type of permission the shared account user has. Users can select the following options:

1. Display IBAN and BIC: Allows the user to see and share your account details -> "IBAN"

2. Showing History: The user will see only part of transaction history -> "ALL_TRANSACTIONS"

3. Make Transfer: Allow user to initiate outgoing transfers -> "TRANSFERS"

4. Request Money: Allows user to request money -> "REQUESTS"

5. Cards: Allows user to view cards' details and pause them -> "CARDS"

6. Account Settings: Allows the user to personalise account -> "SETTINGS"

The permissions need to be sent in a list in the request's body. For example, if the user selects only options 1 and 2, then the permission list should be the following:

{
   "permissions":["IBAN","ALL_TRANSACTIONS"]
}

In the above example, only the permission value is shown. You will need some other values as well in the body. See the final API call to understand it better.

Add optional message

Users can add a message when making the sharing request. This is helpful when the other person receives the sharing request.

{
    "message":"Hello, this is John Doe requesting for the account sharing!"
}

Make the account-sharing request.

To make the final API call to account sharing request, have a look at the request below:

shareAccount

Required scopes - accounts Enhanced security through pin, password or challenge - as applicable - required, based on jurisdiction and/or client configuration

POST//accounts:8080v1/accounts/{id}/sharing-requests

Path parameters

id*string

id

Body

application/json

body

contact*ContactDetail

messagestring

permissions*array of enum

Response

200201401403404

OK

Body

application/json

idstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080v1/accounts/{id}/sharing-requests', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "contact": {
        "detail": "text",
        "type": "EMAIL"
      },
      "permissions": [
        "TRANSFERS"
      ]
    }),
});
const data = await response.json();

Response

{
  "id": "text"
}

For this request, you have to make sure that a challenge id is available as 'X-AAZZUR-DEVICE-CHALLENGE' and a signature is available as 'X-AAZZUR-SIGNATURE'. To know more about how to generate it, please read through the process available on the Device Verification Page.

Accepting the Sharing Request

After making a sharing request, the recipient's account will get a notification. To get the notifications make a GET request to the below endpoint:

getPullNotifications

GET//notifications:8080/v1/notifications

Response

200401403404

OK

Body

application/json

dataobject

idstring

timestring (date-time)

typeenum

ACCOUNT_SHARING_ACCEPTEDACCOUNT_SHARING_REJECTEDACCOUNT_SHARING_REQUESTEDACCOUNT_UNSHAREDADDED_SHARED_ACCOUNT_USERSHARED_ACCOUNT_PERMISSIONS_UPDATEDACCOUNT_TAG_UPDATEDACCOUNT_IMAGE_UPDATEDCARD_ISSUEDCARD_ACTIVATEDCARD_RESUMEDCARD_PAUSEDCARD_BLOCKEDSHARED_ACCOUNT_TRANSFER_REQUESTEDLOGIN_CONFIRMATION

Request

JavaScriptCurl

const response = await fetch('//notifications:8080/v1/notifications', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

[
  {
    "id": "text",
    "time": "2024-05-06T11:29:11.061Z",
    "type": "ACCOUNT_SHARING_ACCEPTED"
  }
]

If an account-sharing request is available, then the response will be something like this below:

[
    {
        "id": "9d570969-aa25-469a-b2a0-7a673c463728",
        "time": "2022-12-26T03:55:03.410+00:00",
        "type": "ACCOUNT_SHARING_REQUESTED",
        "data": {
            "initiatorName": "John Doe",
            "message": "",
            "requestId": "1922f501-da26-4db6-b802-3c31722f1d9fhin",
            "permissions": [],
            "tag": "Sample Account Name"
        }
    }
]

Look at the type value; you can filter the type of notifications. If the value of type is "ACCOUNT_SHARING_REQUESTED" then that notification is a sharing request notification and in the data object, all the data required to accept or reject the request can be found.

Have a look at the below endpoint that is used for accepting the shared-account request:

acceptRequest

Required scopes - accounts Enhanced security through pin, password or challenge - as applicable - required, based on jurisdiction and/or client configuration

POST//accounts:8080/v1/account-sharing-requests/{id}/approval

Path parameters

id*string

id

Response

200201401403404

OK

Body

application/json

statusstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/account-sharing-requests/{id}/approval', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

{
  "status": "text"
}

Rejecting / Declining the Sharing Request

Users can also reject the request with the below request by using the below endpoint:

rejectRequest

Required scopes - accounts

POST//accounts:8080/v1/account-sharing-requests/{id}/rejection

Path parameters

id*string

id

Body

application/json

body

messagestring

Response

200201401403404

OK

Body

application/json

statusstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/account-sharing-requests/{id}/rejection', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "status": "text"
}

Here the id is the requestId from the notification data object.

After you're done with a notification, you will have to remove the notification because otherwise, it's gonna stay in the GET notification request's response.

Make a DELETE Request to the below endpoint with the notification id to remove it:

deletePullNotification

DELETE//notifications:8080/v1/notifications/{id}

Path parameters

id*string

id

Response

200204401403

OK

Body

application/json

statusstring

Request

JavaScriptCurl

const response = await fetch('//notifications:8080/v1/notifications/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

{
  "status": "text"
}

Cancelling an Account-Sharing Invitation

The user making the account-sharing request can also cancel the request before the request is processed. To cancel the request, make a DELETE request:

unshareAccount

Required scopes - accounts Enhanced security through pin, password or challenge - as applicable - required, based on jurisdiction and/or client configuration

DELETE//accounts:8080/v1/accounts/{accountId}/sharing-configurations/{id}

Path parameters

accountId*string

accountId

id*string

id

Response

200204401403

OK

Body

application/json

statusstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/accounts/{accountId}/sharing-configurations/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

{
  "status": "text"
}

For this request, you have to make sure that a challenge id is available as 'X-AAZZUR-DEVICE-CHALLENGE' and a signature is available as 'X-AAZZUR-SIGNATURE'. To know more about how to generate it, please read through the process available on the Device Verification Page.