Skip to main content

Linked Account Verification Flow

Works In Progress

This feature will be made available in Sandbox, as from Wednesday 18th September 2024 for UK-based programmes only.

Verification Steps Required for Linked Accounts​

Feature for UK-based Programmes
  • The Linked Account feature is currently mandatory on UK Cards-Focused programmes, with Identities that hold GBP Managed Accounts for use with Managed Cards. This means that the new feature is available for UK-based programmes only.
  • Linked Accounts are not yet available for EU/EUR/SEPA programmes.

The activation of a Linked Account requires the successful completion of three verification steps as explained in this page:

Declaration of Ownership via SCA Challenge​

When adding a Linked Account, it is critical to confirm that the registered account belongs to the Identity attempting to link it. As part of this process, the ownership declaration is facilitated through a Strong Customer Authentication (SCA) challenge. Upon initiating the Linked Account registration process, the Root User of the Identity must complete an SCA challenge to declare ownership of the Linked Account.

When calling the GET /linked_accounts/{id}/verifications, the step:ROOT_USER_DECLARATION_SCA_CHALLENGE would be in status:PENDING_USER indicating that end-user action is required. If status:COMPLETED, this means that the end-user already actioned the declaration of ownership.

If step:ROOT_USER_DECLARATION_SCA_CHALLENGE is in status:PENDING_USER, trigger the following calls of action:

1. Triggering the SCA Challenge​

Call the endpoint POST /challenges/otp/{channel} with resourceType: linked_account_declaration.

Upon initiating the Linked Account registration request via the API POST /linked_accounts, an SCA challenge must be triggered for the root user. The challenge is delivered through supported channels such as SMS, Twilio Authy, or Biometrics.

Root-User Action

Note that the logged-in user when triggering this endpoint must be a root user. An authorised user cannot trigger the SCA challenge.

2. Completing the Challenge​

The user will receive 6 digit one-time code or a push notification, depending on the configured channel (SMS, Twilio Authy, or Biometrics). This message will reference the declaration of ownership for the Linked Account being registered. The Root User must complete the challenge by inputting the one-time code or confirming through biometric verification.

Once successfully complete, the verificationSteps:ROOT_USER_DECLARATION_SCA_CHALLENGE will change its status from PENDING_USER to COMPLETED.

Control Check Through a Test Funding Transaction​

As part of the verification process for verifying a Linked Account, the Identity must demonstrate control over the external account by performing a test funding transaction. This is a critical step to ensure the account is controlled by the registered identity.

When calling the GET /linked_accounts/{id}/verifications, the step:TRANSFER_INSTRUCTION would be in status:PENDING_USER indicating that end-user action is required. If status:COMPLETED, this means that the end-user already actioned the transfer instruction.

If step:TRANSFER_INSTRUCTION is in status:PENDING_USER, trigger the following call of action:

Initiating the Test Funding Transaction​

Upon registering the Linked Account, the Corporate (or Consumer in certain programmes) is required to initiate a wire transfer from the external account to any Managed Account that belongs to the same identity within the system. The transaction should follow the specific transfer instructions provided in the embedder’s application, which are provided by calling the following endpoint to retrieve the TRANSFER_INSTRUCTION details:

GET/linked_accounts/{id}/verificationsTry it

The details object include:

  • Transfer Amount: Provided in the amount object, this is a predefined currency and amount that must match.

  • Transfer Reference: Provided in the reference field, this is a unique reference provided by the system to identify the transaction.

Upon receiving this payment, Weavr automatically performs a comparison to the previously registered Linked Account and the test funding transaction requirements. The verification logic is based on two important details: the details of the source external account and the matching transfer reference, with the matching transfer amount being used as a fallback if the reference did not work.

Check 1: Source Account Details:

  • If the details of the source external account on the received test transfer do not match the Linked Account being registered, the Linked Account will be Rejected (overall status).
  • If the details of the source external account on the received test transfer match the Linked Account being registered, we proceed with checking the transfer reference.

Check 2: Test Transfer Reference:

  • If the reference has an exact match, the state for TRANSFER_INSTRUCTION is changed to Verified.
  • If the reference does not match, check 3 is performed.

Check 3: Test transfer amount:

  • If the amount matches, the state for TRANSFER_INSTRUCTION is changed to Verified (i.e. regardless of the test transfer reference).
  • Otherwise, if the amount does not match, the funding transaction will require an internal check by Weavr.

This step proves that the Linked Account as registered matches an external account that is controlled by the Identity, satisfying the final requirement in the Linked Account verification process.

Internal Checks by Weavr​

A name verification check will be automatically triggered by the Weavr platform and, when necessary, flagged for review by the Weavr Compliance team. This ensures that the name of the Linked Account holder matches the Identity registered with Weavr. The internal checks are required as another layer in the verification process to verify that the Linked Account belongs to the same person or business entity as the Managed Account.

When calling the GET /linked_accounts/{id}/verifications, the step:INTERNAL_CHECKS would be in status:PENDING_REVIEW indicating that Weavr action is required. If status:COMPLETED, this means that the Weavr Compliance team has completed the required internal verification checks.

Linked Account Verification Flow​

What follows is the recommended implementation flow for the Linked Account registration process and how to trigger the various verification steps:

  1. Call POST /linked_accounts for your end-user to start the registration of a Linked Account. The section ‘Key Fields in Linked Account Registration’ explains the required fields that an end-user would need to input for the Linked Account to get to the first state PENDING_VERIFICATION.

  2. Trigger an SCA challenge to the Identity root user by calling the endpoint POST /challenges/otp/{channel} with resourceType:linked_account_declaration.

  3. Call the endpoint GET /linked_accounts/{id}/verifications to instruct the Identity root user to perform the funding transaction from the Linked Account being registered to the Managed Account owned by the same Identity. Funding instructions are presented in the endpoint in the details object within the verificationSteps object.

  4. INTERNAL_CHECKS will be performed by the Weavr platform to verify that the Linked Account belongs to the registered Identity.

  5. Once all steps are verified, the Linked Account becomes Active, allowing the user to make or receive payments for self-to-self transactions.

Linked Account Webhook Event​

Please note that we are working on a webhook event to inform you as Linked Account verification states transitions between different states. More information will be shared in the upcoming releases.

Linked Account Webhook Event​

Notifications of updates to linked accounts will be sent to you via ${WEBHOOK_URL}/linked_accounts/watch webhook URL.

info

The ${WEBHOOK_URL} is the URL configured in your application settings.

This webhook is triggered whenever there is an event related to a linked account; such as activation, rejection, blocking, removal, or the change in state of a verification step. The webhook provides detailed information about the status of the linked account and any verification processes associated with it.

Integration to this webhook is strongly recommended in order to track the lifecycle of a linked account, including the progress towards verifying an account that has recently been created. It can notify your system about account activation, rejection, or other statuses, helping ensure timely updates to your end-customers regarding their linked account.

Check the detailed description of the webhook parameters here.