Beneficiaries Overview
Create and manage a list of beneficiaries for your customers.
A beneficiary includes both information about the business or individual as well as their bank account or instrument details used to make payments to.
When using beneficiaries, your customers may be allowed to skip Strong Customer Authentication when executing Outgoing Wire Transfer or Send transactions, thus reducing the number of approval steps required.
Create Beneficiaries
To create a beneficiary for an identity, an end-user belonging to the identity must be logged in. You will require your API key and an active end-user authentication token to create a beneficiary. Read more about authentication in the authentication guide.
We currently only support TRUSTED beneficiaries. Creating beneficiaries that are still not trusted beneficiaries will be supported in the future.
Setting the trustLevel of a beneficiary to TRUSTED will enable the end-user to skip Secure Customer Authentication for transactions to that beneficiary.
Beneficiaries belong to the identity managing them and cannot be shared with other identities.
Verify Beneficiaries
Before the submitted beneficiaries can be added to the list, the logged-in user must verify the details by completing a challenge.
A challenge is required when removing beneficiaries from the list as well.
Send a Challenge
You can trigger the beneficiaries verification process by calling the beneficiaries' challenge API. The user will be requested to perform a two-factor authentication based on the channel provided in the request.
You can check your enabled authentication channels for beneficiaries via the Innovator Portal by navigating to Identities Profile → Authentication tab → Payment Verification.
Currently, we support SMS and AUTHY as possible authentication channels. More authentication channels will be added in the future.
You can start an SCA challenge via SMS by requesting the One Time Password API endpoint. A text message containing a OTP code will be sent to the logged-in end-users' registered mobile phone.
Alternatively, you can use Twilio AUTHY to send a push notification on the user's mobile phone.
Complete the Challenge
If SMS was the selected channel, then you must build a page in your application where the user can enter the verification code that they received in the text message which you will need to submit to via the challenge verify API.
In case of Twilio AUTHY, the user must approve the push notification submitted on their mobile phone. You will receive a webhook notification once the user approves or rejects the push notification.
Once confirmed, the beneficiaries will be automatically added to the identity's beneficiary list. You will receive a webhook for the batch of beneficiaries that will include all the beneficiaries in the list with its outcome.
Remove Beneficiaries
To remove a beneficiary for an identity, an end-user belonging to the identity must be logged in. You will require your API key and an active end-user authentication token to remove a beneficiary. Read more about authentication in the authentication guide.
The logged-in user must complete an SCA challenge to remove beneficiaries.
Using Beneficiaries with Transactions
When submitting Outgoing Wire Transfer or Send transactions, your customers can choose to provide a beneficiary instead of the destination instrument details. This can be done by providing a beneficiaryId in the destination parameter.
If the Send or Outgoing Wire Transfer was eligible to skip Strong Customer Authentication because the destination instrument is a trusted beneficiary, then it will be executed automatically and the challengeExemptionReason will be set to TRUSTED_BENEFICIARY.