# Implementing mandates

## Prerequisites

- **Authentication scopes** — `mandates:admin`
For more information, refer to [Authentication scopes](/products/byol/concepts/api_concepts/authentication/authentication_oauth#list-of-authentication-scopes).
- **Webhook handler ready** — Set up a webhook endpoint to listen for direct debit events.
  - Subscribe to [`DIRECT_DEBIT.*`](/products/byol/guides/payments/payments_webhooks) events.
For more information, refer to [Implementing webhooks](/products/byol/getting_started/implementing_webhooks).


Before a mandate can be set up, the [user](/products/byol/guides/users/users_onboarding_overview) or [business](/products/byol/guides/accounts/businesses_overview) 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`](/api/mandates/create_mandate) including a `confirmed_at` value.

Any additional mandate data required will be populated by Upvest.

### Example creating a mandate for an end user

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

Response
```json
{
  "id": "9c5a7dea-46f2-4502-b6b5-9902a53860e4",
  "created_at": "2020-08-24T14:15:22Z",
  "user_id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202",
  "iban": "DE8900**********0000",
  "bic": "ABCDEXXX",
  "creditor_name": "Creditor Company",
  "creditor_id": "DE98ZZZ09999999999",
  "creditor_address":{
    "address_line1": "Strasse 1",
    "address_line2": "Company GmbH",
    "postcode": "12345",
    "city": "Berlin",
    "state": "BE",
    "country": "DE"
  },
  "type":"RECURRENT",
  "confirmed_at": "2021-12-08T08:38:48.021Z"
}
```

### Example creating a mandate for a business entity

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

Response
```json
{
  "id": "9c5a7dea-46f2-4502-b6b5-9902a53860e4",
  "created_at": "2020-08-24T14:15:22Z",
  "business_id": "b3e4f5a6-1234-4c78-9abc-def012345678",
  "iban": "DE8900**********0000",
  "bic": "ABCDEXXX",
  "creditor_name": "Creditor Company",
  "creditor_id": "DE98ZZZ09999999999",
  "creditor_address": {
    "address_line1": "Strasse 1",
    "address_line2": "Company GmbH",
    "postcode": "12345",
    "city": "Berlin",
    "state": "BE",
    "country": "DE"
  },
  "type": "RECURRENT",
  "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](/products/byol/guides/payments/payments_webhooks)

## Next steps

Now you are ready to jump into [triggering direct debit funding](/products/byol/guides/payments/direct_debit/direct_debit_submitting).