# Create Mandate (Link Account)
source: https://developer.mastercard.com/ob-accept-payments/documentation/tutorials-and-guides/create-mandate-tutorial/index.md

This guide provides instructions on how to create and authorize a mandate request, and how to get the mandate status.

Refer to [Payment Mandates](https://developer.mastercard.com/ob-accept-payments/documentation/payments/vrp/vrp/index.md) for additional details.

## Prerequisites {#prerequisites}

* You have been onboarded to Open Finance and obtained a `destinationId` to receive payments (refer to the [Quick Start](https://developer.mastercard.com/ob-accept-payments/documentation/quickstart/index.md) guide).
* Your `redirectURL`, where the PSU is redirected after the authorization, have been allowlisted as part of onboarding.
* You have successfully authenticated with the API (refer to the [Authentication](https://developer.mastercard.com/ob-accept-payments/documentation/api-basics/index.md) guide).

## Step 1 - Specify the Scheme / Payment Rail {#step-1---specify-the-scheme--payment-rail}

To create a mandate through Open Finance, you need to specify which scheme / payment rail will be used for processing the payments associated with the mandate.

Refer to [Supported Payment Rails](https://developer.mastercard.com/ob-accept-payments/documentation/production/supported-payments-rails/index.md) to learn more about the payment rails in different regions.

Identify the payment rail that you will use and record the payment rail and currency associated with it for the next step.

## Step 2 - Assign PSU IDs {#step-2---assign-psu-ids}

Assign a unique identifier for each consumer (Payment Services User), `endUser.id`.

For the UKFasterPayments payment rail, you are strongly encouraged to prepare the following context values:

* `contextCode`
* `purposeCode`
* `deliveryAddress`

These are used by UK banks for risk scoring. Refer to [Supported Payment Rails](https://developer.mastercard.com/ob-accept-payments/documentation/production/supported-payments-rails/index.md) for more details about each field as well as accepted values.

## Step 3 - Create Mandate {#step-3---create-mandate}

Once you have identified the scheme / payment rail from the previous step and collected the parameters needed for it, you can create a mandate and retrieve a `flowUr`\* for users to authorize the mandate.

API Reference: `POST /mandates`

### Request {#request}

* Use the `paymentRail` and `currency` identified during previous step. Note that scheme rules will be applied automatically to the fields in the message
* Use the `destinationId` that you obtained from onboarding.
* Specify a `redirectURL` where the user will be redirected after finishing the Mandate flow.
* Specify a reference for your mandate. You will need to use same reference for all payments using this mandate. This may be useful for reconciliation.
* Depending on your payment rails, populate the fields in the *context* section with values identified at the previous step.
* Only specify pre-selected `providerId` if you have an outsourcing agreement with Mastercard Open Finance Pay.

### Response {#response}

If the request is successful, the response will look like:

```json
{
  "flowUrl": "https://mtf.connect.openbanking.mastercard.eu/start/storage-payments/472e651e-5a1e-424d-8098-23858bf03ad7",
  "mandateId": "81506a92-d746-43d2-9a8b-03ef4383f8fd"
}
```

* Record the `mandateId` for the next steps.
* Redirect the user to the `flowUrl` to start the mandate authorization flow.

## Step 4 - Redirect {#step-4---redirect}

Redirect the user to the `authorizationUrl` received in the previous step to authorize the mandate.
Note: The `flowUrl` must not be presented in an iframe, and it cannot be reused.

A flow will be displayed to the user where they will be able to:

* Select their provider / bank
* Go through an SCA with the provider
* Select the account to pay from and complete the payment.

#### Example Authorization Flow {#example-authorization-flow}

**Mastercard Open Finance Pay screens**   

The user must select their bank and accept the agreement.
![Mastercard-Open-Banking-Screen 1](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/create-man_1.png)
![Mastercard-Open-Banking-Screen 2](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/create-man_2.png)

**Provider screens**   

The user must select their account and authorizes the payment.
![Provider-screen 1](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/create-man_3.png)
![Provider-screen 2](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/create-man_4.png)
![Provider-screen 4](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/create-man_6.png)

**Mastercard Open Finance Pay screen**   

Confirmation of the payment is displayed.
![Mastercard-Open-Banking-Screens](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/create-man_7.png)

## Step 5 - Retrieve Mandate State {#step-5---retrieve-mandate-state}

After the mandate authorization flow is completed, the user is redirected back to your application using the `redirectUrl`. Retrieve the latest state of the mandate using the Get Mandate endpoint.

API Reference: `GET /mandates/{mandate_id}`

### Request {#request-1}

Use the `mandateId` retrieved from the second step as the `mandate_id` path parameter to get the mandate status.

### Response {#response-1}

If the request is successful, the response will look like:

```json
{
  "mandateId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "destinationId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "paymentRail": "UkFasterPayments",
  "reference": "Example Reference",
  "providerId": "GB_TestBank",
  "currency": "GBP",
  "providerMandateId": "Example Provider Mandate ID",
  "displayName": "****0604",
  "endUser": {
    "id": "0001789937234"
  },
  "context": {
    "contextCode": "BillingGoodsAndServicesInAdvance",
    "purposeCode": "GDSV",
    "deliveryAddress": {
      "addressLines": [
        "string"
      ],
      "street": "Street Name",
      "buildingNumber": "42",
      "postalCode": "1234",
      "city": "London",
      "countrySubDivision": "Greater London",
      "country": "GB"
    }
  },
  "limits": {
    "validTo": "2024-02-21",
    "maxAmountPerPayment": 100,
    "maxAmountPerMonth": 1000
  },
  "status": {
    "code": "string",
    "lastUpdated": "2023-10-30T10:10:00.7539418+00:00",
    "events": [
      {
        "event": "REQUESTED",
        "timestamp": "2024-01-17T12:29:36.919957+00:00"
      }
    ],
    "details": {
      "code": "",
      "reason": "Reason"
    }
  },
  "revoked": false
}
```

Handle different mandate outcomes based on the returned mandate status code and reason code.

You can also receive mandate status updates through [Webhooks](https://developer.mastercard.com/ob-accept-payments/documentation/event-notifications/index.md).