# Create a Payment Link
source: https://developer.mastercard.com/ob-accept-payments/documentation/tutorials-and-guides/create-payment-link-tutorial/index.md

This guide walks you through creating a Payment Link request, authorizing the payment and getting the payment status.

Refer to [Payment Links](https://developer.mastercard.com/ob-accept-payments/documentation/features/payment-links/index.md) for a more detailed description for this scenario.

## Prerequisites {#prerequisites}

* You have been onboarded to Mastercard Open Finance Pay 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 Payment Link through Mastercard Open Finance Pay, you need to specify which Payment Rails will be used by the ASPSP / Provider for processing the payment.

You can learn more about the payment rails in different regions [here](https://developer.mastercard.com/ob-accept-payments/documentation/production/supported-payments-rails/index.md).

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

## Step 2 - Identify Additional Values {#step-2---identify-additional-values}

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. See [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 a Payment Link {#step-3---create-a-payment-link}

Once you have identified the scheme / payment rail from the previous step and collected the parameters needed for it, you can create a Payment Link and retrieve a flowUrl for users to authorize the payment.

API Reference: `POST /payment-links`

### 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 Payment flow.
* Specify the `expiryDate` to define how long you want the Payment Link to live for.
* Specify a reference for your Payment. 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
{
  "paymentLinkId": "4b26afc8-79a1-4bf9-8cc4-7a1a02aa8133",
  "flowUrl": "https://mtf.connect.openbanking.mastercard.eu/start/storage-payments/472e651e-5a1e-424d-8098-23858bf03ad7"
}
```

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

## Step 4 - User Payment Authorization Flow {#step-4---user-payment-authorization-flow}

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

A flow displays where the user can will be able to select their provider, go through an SCA with the provider, and select the account to pay from and complete the payment.

An example flow is displayed here:

#### Mastercard Open Finance Pay Screens {#mastercard-open-finance-pay-screens}

![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/create_pay_link_1.png)   
![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/create_pay_link_2.png)

#### Example of Provider Screens {#example-of-provider-screens}

![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/create_pay_link_3.png)   
![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/create_pay_link_4.png)

#### Mastercard Open Finance Pay Screens {#mastercard-open-finance-pay-screens-1}

![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/create_pay_link_6.png)

## Step 5 - Payment Link Status Webhook Notification {#step-5---payment-link-status-webhook-notification}

When the Payment Link status changes you will receive webhook notifications from the Mastercard Open Finance Pay API of `type="PaymentLinkStatusUpdated""`.

An example of how the webhooks content should appear:

```json
{
  "type": "PaymentLinkStatusUpdated",
  "data": {
    "paymentLinkId": "acb29db6-70df-4c99-888c-d8485cd40c3d",
    "executionTime": "2024-01-01T12:34:56.123456+00:00",
    "status": {
      "code": "SUCCEEDED",
      "lastUpdated": "2025-05-12T15:23:39.969894+00:00"
    }
  },
  "retryCount": 0
}
```

## Step 6 - Payment Link Payment Attempted Webhook Notification {#step-6---payment-link-payment-attempted-webhook-notification}

When a payment has been attempted using the Payment Link, you will receive webhook notifications from Mastercard Open Finance Pay of `type="PaymentLinkPaymentAttempted"`.

An example of how the webhooks content should appear:

```json
{
  "type": "PaymentLinkPaymentAttempted",
  "data": {
    "paymentLinkId": "acb29db6-70df-4c99-888c-d8485cd40c3d",
    "paymentId": "77040d5a-f9d7-4049-baae-0be2e11de4a4",
    "executionTime": "2024-01-01T12:34:56.123456+00:00"
  },
  "retryCount": 0
}
```

Record the `paymentId` for use later on with X flow.

## Step 7 - Payment Status Webhook Notification {#step-7---payment-status-webhook-notification}

Once a payment has been attempted using the Payment Link you should be prepared for receiving webhooks on the new `paymentID` and keep track that the new payment is related to this Payment Link. When the Payment status changes you will receive webhook notifications from Mastercard Open Finance Pay of `type="AcceptPaymentStatusUpdated"`.

An example of how the webhooks content should appear:

```json
{
  "type": "AcceptPaymentStatusUpdated",
  "data": {
    "paymentId": "acb29db6-70df-4c99-888c-d8485cd40c3d",
    "executionTime": "2024-01-01T12:34:56.123456+00:00",
    "status": {
      "code": "AUTHORIZATION_FLOW_INCOMPLETE",
      "lastUpdated": "2025-05-12T15:23:39.969894+00:00"
    }
  },
  "retryCount": 0
}
```

## Step 8 - Payment Initiation Result {#step-8---payment-initiation-result}

After the payment authorisation flow is completed, the user is redirected back to your application using the *redirectUrl*. Retrieve the latest state of the payment using the Get Payment endpoint.

API Reference: `GET payments/{payment_id}`

### Request {#request-1}

Use the `paymentId` retrieved from the sixth step as the `payment_id` path parameter to get the payment status.

### Response {#response-1}

```json

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

{
  "paymentId": "acb29db6-70df-4c99-888c-d8485cd40c3d",
  "destinationId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "paymentRail": "UkFasterPayments",
  "amount": 123.5,
  "currency": "GBP",
  "status": {
    "code": "string",
    "lastUpdated": "2023-10-30T10:10:00.7539418+00:00",
    "events": [],
    "details": {}
  },
  "reference": "Example Reference",
  "identifier": "Example ID",
  "endToEndId": "Example ID",
  "providerId": "GB_TestBank",
  "date": {
    "requestedDate": "2024-02-21",
    "actualDate": "2024-02-22"
  },
  "context": {
    "contextCode": "BillingGoodsAndServicesInAdvance",
    "purposeCode": "GDSV",
    "deliveryAddress": {}
  },
  "providerPaymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "endUser": {
    "id": "0001789937234"
  },
  "clientAssignedReference": "Example client assigned reference"
}
```

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

You can also receive payment status updates through webhooks.