Implementing mandates

Prerequisites

Authentication scopes — mandates:admin
For more information, refer to Authentication scopes.
Webhook handler ready — Set up a webhook endpoint to listen for direct debit events.
- Subscribe to DIRECT_DEBIT.* events.
For more information, refer to Implementing webhooks.

Before a mandate can be set up, the user or business must be onboarded and active on the Upvest platform.

Creating a validated mandate

Once the end user's or business entity's bank account details have been captured and a mandate is authorised, you can trigger a mandate creation request with

POST /payments/mandates including a confirmed_at value.

Any additional mandate data required will be populated by Upvest.

Example creating a mandate for an end user

{
  "user_id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202",
  "iban": "DE89000000000000000000",
  "bic": "ABCDEXXX",
  "confirmed_at": "2021-12-08T08:38:48.021Z"
}

Example creating a mandate for a business entity

{
  "business_id": "b3e4f5a6-1234-4c78-9abc-def012345678",
  "iban": "DE89000000000000000000",
  "bic": "ABCDEXXX",
  "confirmed_at": "2021-12-08T08:38:48.021Z"
}

The bank account used for the mandate may differ from the end user's reference bank account.
All mandates created are assigned the type RECURRENT.

Recommended: Use webhooks to track mandate and direct debit status

After creating a mandate, the user can then initiate direct debit funding. Set up a webhook listener for DIRECT_DEBIT.* events to track the direct debit lifecycle from NEW through PROCESSING to CONFIRMED.

For more information, refer to Payment webhook events

Next steps

Now you are ready to jump into triggering direct debit funding.