Implementing mandates

Prerequisites

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

Creating a validated mandate

Once the user’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 request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Mandate - Create - Request",
  "type": "object",
  "properties": {
    "user_id": {
      "$ref": "../users/user_id.v1.json"
    },
    "iban": {
      "description": "Mandate IBAN of which debit will be drawn",
      "$ref": "../common/iban.v1.json"
    },
    "bic": {
      "description": "The BIC of the IBAN of which debit will be drawn",
      "$ref": "../common/bic.v1.json"
    },
    "confirmed_at": {
      "description": "Timestamp of when user validated the mandate",
      "$ref": "mandate.v1.json#/properties/confirmed_at"
    }
  },
  "required": [
    "iban",
    "bic",
    "confirmed_at"
  ],
  "additionalProperties": false
}

Example response

{
  "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"
}

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

Next steps

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