Managing trusted payees

Customers pay the same people over and over - a landlord, a supplierSupplier A trusted business or individual that receives payments from Buyers through payment runs. Suppliers can be stored in a trusted supplier list, and when marked as trusted, may allow Buyers to skip Strong Customer Authentication when executing payment runs to those suppliers., a payroll provider. A trusted payee lets them save a recipient once so future payments skip re-entering destination details and, because the payee is trusted, skip Strong Customer Authentication too. This page builds the address-book feature of your app.

Where this fits

This page builds on authentication and making payments. Managing trusted payeesTrusted Payee A trusted recipient for payments, including the business or individual's details and their bank account or instrument details. Sending to a Trusted Payee may let customers skip Strong Customer Authentication (SCA) on Outgoing Wire Transfer or Send transactions, reducing the number of approval steps required. Previously referred to as a Beneficiary. requires a logged-in end-user, and every add or remove is protected by an SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics). challenge.

Here's the trusted-payees screen you'll build. The saved list and the add-and-verify flow are all API-driven - each pinPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. shows the endpoint behind it:

your app

Trusted payees

Saved recipients

AAcme Ltd•• 8619 · GBP

RRiya Patel•• 4402 · EUR

1API · data sourcePOST/beneficiariesSaved payeesTrusted payees are created once with trustLevel TRUSTED and reused by beneficiaryId on future payments.View docs →

Add a payee

2API · data sourcePOST/beneficiaries/batch/{id}/challenges/otp/{channel}Verify to saveA new payee is verified with an SCA challenge - trigger a one-time password to the user's enrolled number.View docs →

SDK component (renders the area)API endpoint (the data source)

Hover or focus a numbered pin to see which Weavr secure component renders the area, or which API endpoint supplies its data - then click to open the docs.

What a trusted payee is

A trusted payeeTrusted Payee A trusted recipient for payments, including the business or individual's details and their bank account or instrument details. Sending to a Trusted Payee may let customers skip Strong Customer Authentication (SCA) on Outgoing Wire Transfer or Send transactions, reducing the number of approval steps required. Previously referred to as a Beneficiary. is a saved recipient - the account holder plus the bank account or instrumentInstrument A financial product owned by an Identity. There are two types: Managed Accounts (stored-value accounts that hold balances and can receive wire transfers) and Managed Cards (prepaid cards - virtual or physical - used for purchases). that receives funds - persisted on a customer and reused across transactions. Set one up once, then reference it by beneficiaryId on future sends and outgoing wire transfers instead of re-entering the destination.

"Beneficiaries" are trusted payees

We used to call these beneficiaries and renamed them to trusted payeesTrusted Payee A trusted recipient for payments, including the business or individual's details and their bank account or instrument details. Sending to a Trusted Payee may let customers skip Strong Customer Authentication (SCA) on Outgoing Wire Transfer or Send transactions, reducing the number of approval steps required. Previously referred to as a Beneficiary.. You'll still see beneficiary in some API field names (such as beneficiaryId) - they mean the same thing.

Step 1: Create a trusted payee

Your app collects the recipient's details and your backend submits them. This needs the customer's api-key and a logged-in user's Auth Token.

POST/beneficiariesTry it

Request

{
  "tag": "string",
  "beneficiaries": [
    {
      "trustLevel": "TRUSTED",
      "externalRefs": [
        "string"
      ],
      "group": "string",
      "beneficiaryInformation": {
        "businessName": "string"
      },
      "beneficiaryDetails": {
        "instrument": {
          "id": "string",
          "type": "managed_cards"
        }
      }
    }
  ]
}

Response

{
  "operationBatchId": {
    "batchId": "string",
    "operation": "CREATE"
  },
  "tag": "string",
  "state": "INITIALISED"
}

Set trustLevel to TRUSTED so the customer can later skip Strong Customer Authentication when paying this recipient. TRUSTED is currently the only supported level.

Payees belong to one customer

Trusted payeesTrusted Payee A trusted recipient for payments, including the business or individual's details and their bank account or instrument details. Sending to a Trusted Payee may let customers skip Strong Customer Authentication (SCA) on Outgoing Wire Transfer or Send transactions, reducing the number of approval steps required. Previously referred to as a Beneficiary. are private to the customer that created them and can't be shared with other customers.

Step 2: Verify the payee with a challenge

A new trusted payeeTrusted Payee A trusted recipient for payments, including the business or individual's details and their bank account or instrument details. Sending to a Trusted Payee may let customers skip Strong Customer Authentication (SCA) on Outgoing Wire Transfer or Send transactions, reducing the number of approval steps required. Previously referred to as a Beneficiary. isn't usable until the logged-in user verifies it with an SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics). challenge. This is where your app reuses the step-up UI you already built.

Send the challenge

Trigger a one-time password over SMS to the user's enrolled mobile number:

POST/beneficiaries/batch/{id}/challenges/otp/{channel}Try it

Response

{
  "code": "string",
  "message": "string"
}

Complete the challenge

Build a screen where the user enters the code, then submit it to verify the batch:

POST/beneficiaries/batch/{id}/challenges/otp/{channel}/verifyTry it

Request

{
  "verificationCode": "string"
}

Response

{
  "code": "string",
  "message": "string"
}

Once verified, the payees are added to the customer's list automatically. You receive a webhook for the batch with the outcome for each payee - use it to update your app's saved-payees screen.

Step 3: Pay a trusted payee

With a trusted payeeTrusted Payee A trusted recipient for payments, including the business or individual's details and their bank account or instrument details. Sending to a Trusted Payee may let customers skip Strong Customer Authentication (SCA) on Outgoing Wire Transfer or Send transactions, reducing the number of approval steps required. Previously referred to as a Beneficiary. saved, paying them is a normal send or outgoing wire transfer - but instead of destination details, you pass the beneficiaryId in the destination field.

Because the payee is trusted, an eligible payment executes automatically without an extra SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics). challenge, and its challengeExemptionReason is set to TRUSTED_BENEFICIARY. That's the payoff: your customer approves a recipient once, then pays it repeatedly with fewer taps.

Step 4: Remove a trusted payee

Removing a payee is also SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics).-protected - the logged-in user must complete a challenge, exactly like adding one.

POST/beneficiaries/removeTry it

Request

{
  "beneficiaryIds": [
    "string"
  ]
}

Response

{
  "operationBatchId": {
    "batchId": "string",
    "operation": "CREATE"
  },
  "tag": "string",
  "state": "INITIALISED"
}

Removal always requires SCA

There's no exemption for removal - the user must clear an SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics). challenge to take a payee off the list. Reuse the same OTP flow from step 2.

What you've built

Your app now has a full trusted-payees address book: customers save and verify recipients, pay them with reduced friction, and remove them securely.

Next, build the screens that surface all of this activity: showing activity and statements.