Add payees
Use this when a user wants to save a recipient so they can pay it again without re-entering its details.
It creates a batch containing one or more trusted payees for the logged-in corporate or consumer identity. Once the batch completes, each payee can be referenced by beneficiaryId as the destination of a send or an outgoing wire transfer.
Payees belong to the identity that creates them and can't be shared with other identities.
Fields
Each entry in beneficiaries needs trustLevel set to TRUSTED, plus:
- beneficiaryInformation: who the payee is, as either a business (businessName) or a consumer (name and surname). Length and character limits depend on the payment details supplied below; Faster Payments and BACS are stricter than IBAN.
- beneficiaryDetails: how to pay them, as either an instrument held on the Weavr platform, used for sends, or bankAccountDetails for an external account, used for wire transfers.
group and externalRefs are yours to use (a category for filtering, and your own identifiers for the payee) and don't affect processing.
Verification is required
The batch isn't applied when you create it. The response carries an operationBatchId and a state:
| State | What to do |
|---|---|
| PENDING_CHALLENGE | Issue an SCA challenge and verify it. |
| CHALLENGE_COMPLETED | Verification succeeded; the batch is being applied. |
| COMPLETED | The payees are on the trusted list and can be paid. |
| CHALLENGE_FAILED | Verification failed. The payees weren't added. |
| FAILED | The batch couldn't be applied. |
While the state is PENDING_CHALLENGE, issue a challenge with one-time password or push notification, then confirm it with Verify a payee batch. Verification covers the whole batch, not individual payees.
Next steps
Read the outcome with Get a batch of payees, and the resulting payees with List payees. A payee is usable once it reaches ACTIVE.
Request
- Base URL: https://sandbox.weavr.io/multi
- URL: https://sandbox.weavr.io/multi/beneficiaries
- Auth: HTTP bearer and API key in header api-key
Headers
A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.
Request body
Example request
{
"tag": "customer-123",
"beneficiaries": [
{
"group": "Suppliers",
"beneficiaryInformation": {
"businessName": "Acme Ltd"
},
"beneficiaryDetails": {
"instrument": {
"id": "123456789",
"type": "managed_accounts"
}
}
}
]
}Response
Success
Example response
{
"operationBatchId": {
"batchId": "123456789",
"operation": "CREATE"
},
"tag": "customer-123"
}Changes
No recorded changes to this operation across all 1 revision of this API.