Beneficiary SCA

Strong Customer Authentication (SCA) for Beneficiaries

For some accounts, the regulator requires Strong Customer Authentication (SCA) before a new beneficiary can be used.
When SCA is needed, the Create Beneficiary response includes an scaLink. The end user must open this link and finish the verification.
When they finish, the beneficiary is approved immediately.

Flow overview

1. You call POST /api/v1/Beneficiaries.
2. If SCA is needed, the API returns 202 Accepted. The beneficiary has status Pending and the response includes an scaLink.
3. The end user opens the scaLink.
4. The end user finishes the SCA steps (see below).
5. The beneficiary moves to Approved right away and can be used for payments.

1. Create the beneficiary

POST /api/v1/Beneficiaries
Authorization: Bearer <token>
Content-Type: application/json

{ ...beneficiary details... }

Response when SCA is needed (202 Accepted):

{
  "id": "b7e3c1a2-4d5f-4e6a-8b9c-0d1e2f3a4b5c",
  "status": "Pending",
  ...
  "scaLink": "https://.../sca/Xy7Kp2Qa"
}

If scaLink is null or missing, no SCA is needed and you can ignore this flow.

2. Send the end user to the SCA link

Open scaLink in the end user's browser, in a new tab or an in-app web view.
The end user must complete the process themselves; it cannot be done on their behalf through the API.

3. SCA steps for the end user

1. Set a password: create a password for the secure session.
2. Confirm phone number: enter the one-time code sent by SMS to the user's phone.
3. Verify identity: complete the identity verification step.

4. Beneficiary is approved

When the SCA process ends successfully, the beneficiary moves from Pending to Approved straight away. No manual review is needed.
You can then use the beneficiary for payments.

To confirm the status, call:

GET /api/v1/Beneficiaries/{id}

Good to know

• The link stays valid while the beneficiary is Pending. If the user closes the page before finishing, they can open the same link again. A new secure session is created automatically each time the link is opened.
• Lost the link? GET /api/v1/Beneficiaries/{id} and GET /api/v1/Beneficiaries return the scaLink for every beneficiary that is still waiting for SCA.
• When SCA is done, scaLink is no longer returned.
• A beneficiary that should not go through the SCA process, and in Pending status cannot be used for payments.