# Payment Links source: https://developer.mastercard.com/ob-accept-payments/documentation/features/payment-links/index.md With Payment Links, you can accept one-off payments from the bank account of a Payment Service User (PSU) using a long-lived link. Unlike Variable Recurring Payments (VRPs), the payer must authorize each payment with their bank using Strong Customer Authentication (SCA). A Payment Link is long-lived, so you can share it with the payer while they are not in session, for example inside an emailed bill. The link supports multiple payment attempts until a payment succeeds or the link expires. ## How It Works {#how-it-works} This section explains how to create and use a Payment Link. 1. **Onboard a payment destination.** As part of onboarding, you provide the details of the bank account where the payments are made, known as the destination. After you onboard an account, you receive an identifier to use in the API calls as the `destinationId`. * Depending on your context, for example if you use our Payment Initiation Service Provider (PISP) license, onboarding may include steps to satisfy Anti-Money Laundering (AML) regulations and Know Your Customer (KYC) requirements. You cannot use the destination to create payments before this process is complete. 2. **Authenticate with the API.** Make sure to use the `ob_accept_payments` scope in the request body when you authenticate. Refer to [Authentication](https://developer.mastercard.com/ob-accept-payments/documentation/api-basics/index.md) for detailed instructions on how to authenticate with the service. 3. **Create a Payment Link.** Call the **Create payment link** endpoint. API Reference: `POST /payment-links` Note: **Polymorphic models:** The request models are polymorphic, with a different input model for each payment rail. Each model defines the required inputs and the rules for each input for that rail. For example, the UkFasterPayments rail requires that the currency is set to GBP. Refer to [Payment Link Options](https://developer.mastercard.com/ob-accept-payments/documentation/features/payment-links/index.md#payment-link-options) for the main fields to set in the request. The response returns a `flowUrl`, which you use in the next step, and a `paymentLinkId`, which you can use to get the Payment Link status and the payment attempts made using the Payment Link. 4. **Redirect the payer to the payment authorization flow.** Redirect the payer to the `flowUrl` to start the payment authorization flow. The link is long-lived but valid only until the date set in `expiryDate`. When the payer opens the link, they choose a bank and authorize the payment. After the authorization flow, the payer returns to the redirect URL you provided when you created the Payment Link. * Unlike Single Immediate Payments, the payer can retry the authorization link if it fails. After a payment attempt succeeds, the Payment Link can no longer be used for another payment. Refer to [Example Flow](https://developer.mastercard.com/ob-accept-payments/documentation/features/payment-links/index.md#example-flow) for example screens from the payer journey. 5. **Request the Payment Link details.** Immediately after you create the Payment Link, you can check its status with the **Get payment link** endpoint. The `paymentLinkId` from step 3 is required to fetch the Payment Link details and status. We recommend calling this endpoint after you receive a `PaymentLinkStatusUpdated` webhook, to reduce your infrastructure requirements. Refer to [Payment Link Details](https://developer.mastercard.com/ob-accept-payments/documentation/features/payment-links/index.md#payment-link-details) for an explanation of the details that are returned. API Reference: `GET /payment-links/{payment_link_id}` 6. **Request the details of a payment attempt.** A Payment Link supports multiple payment attempts. Call the **Get payment link payments** endpoint with the `paymentLinkId` from step 3 to get the details and status of each payment attempt. Attempts are returned in ascending order by creation date. We recommend calling this endpoint after you receive a `PaymentLinkPaymentAttempted` webhook, to reduce your infrastructure requirements. Refer to [Payment Attempt Details](https://developer.mastercard.com/ob-accept-payments/documentation/features/payment-links/index.md#payment-attempt-details) for an explanation of the details that are returned. API Reference: `GET /payment-links/{payment_link_id}/payments` You can use the `paymentId` from the response with the [Get payment](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md#getPayment) endpoint to get the details of a specific attempt. 7. **Process webhook notifications for the payment status.** Instead of polling the Payment Link status, we recommend using Mastercard Open Finance webhooks. Webhooks notify you of status changes so you can avoid repeated polling. When we identify that a status has changed, we send you a webhook notification. The available notifications are: * **PaymentLinkStatusUpdated** - Sent when the Payment Link status changes. It includes the `paymentLinkId`. When you receive it, call the [Get payment link](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md#getPaymentLink) endpoint to get the latest status. * **PaymentLinkPaymentAttempted** - Sent when a new payment is attempted using the Payment Link. It includes the `paymentLinkId` and the `paymentId`. When you receive it, call the [Get payment link payments](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md#getPaymentLinkPayments) endpoint to get the payment attempt details. Be prepared to receive webhooks for the new `paymentId`, and track that this payment relates to the Payment Link. You can also use the `paymentId` with the [Get payment](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md#getPayment) endpoint. Refer to [Webhooks](https://developer.mastercard.com/ob-accept-payments/documentation/event-notifications/index.md) for details about the message body, security, and how to process it. 8. **Present the payment status to the payer.** When the payer completes the payment authorization flow, they return to the `redirectUrl` you provided when you created the Payment Link. Mastercard Open Finance appends an extra query parameter, `?paymentId=`, where `` is the ID from step 6 or from the `PaymentLinkPaymentAttempted` webhook. Use this parameter to match with any `AcceptPaymentStatusUpdated` webhook notifications and [Get payment](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md#getPayment) calls, so you can decide what to present to the payer. For security, verify that the `paymentId` matches the one from step 6 or the webhook, because browsers let users change query parameters. Refer to the [Payment Status Model](https://developer.mastercard.com/ob-accept-payments/documentation/payments/payment-status-model/index.md) for a description of all the statuses a payment can be in. Refer to [Errors and Failures](https://developer.mastercard.com/ob-accept-payments/documentation/code-and-formats/index.md) for details on how to handle the failure and non-usable states. ## Payment Link Options {#payment-link-options} The [Create payment link](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md#createPaymentLink) request body has two parts: a top-level `payment` object that holds the payment details, and a top-level `expiryDate`. All the payment fields, including `paymentRail`, `destinationId`, `redirectUrl` and `context`, belong inside the `payment` object, which accepts the same fields as the [Create a payment](https://developer.mastercard.com/ob-accept-payments/documentation/payments/single-immediate-payments/single-immediate-payments/index.md) request. The required fields depend on the payment rail. The following table describes the main options to set when you create a Payment Link: | **Parameter** | **Description** | |-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `paymentRail` | The payment rail that the payer's bank uses to execute the payment. This imposes certain restrictions on the API request and the flow. Refer to [Payment Rails](https://developer.mastercard.com/ob-accept-payments/documentation/production/payment-rails/index.md) for more details. | | `destinationId` | The ID of your onboarded receiving account. Refer to your onboarding data. Your account may have a different ID depending on the environment. | | `redirectUrl` | The URL on your side where the payer is taken on completion of the flow. This URL must be allowlisted, so provide it in the onboarding data we receive from you. | | `expiryDate` | The date the Payment Link expires. After this date, you can no longer accept a payment through the Payment Link. Set an expiry date that gives payers enough time to react. | | `context` | The context in which the payment is made. For the UkFasterPayments rail, we strongly recommend populating this section, because the banks may require it for risk assessment. Refer to [Payment Rails](https://developer.mastercard.com/ob-accept-payments/documentation/production/payment-rails/index.md) for more details. | The following example shows the structure of a Create payment link request for the UkFasterPayments rail: ```json { "payment": { "paymentRail": "UkFasterPayments", "destinationId": "d290f1ee-6c54-4b01-90e6-d701748f0851", "redirectUrl": "https://your-site.example/return", "amount": 100.00, "currency": "GBP", "reference": "Invoice 12345" }, "expiryDate": "2026-12-31T00:00:00.0000000+00:00" } ``` ## Payment Link Details {#payment-link-details} The [Get payment link](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md#getPaymentLink) endpoint returns the following details: | **Field** | **Description** | |------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `paymentRequest` | The details used to create the payment through the Payment Link. These reflect the values passed in the `payment` object of the Create payment link request. | | `createdDate` | The date the Payment Link was created in the Mastercard Open Finance Pay system. | | `expiryDate` | The date the Payment Link expires. After this date, you can no longer attempt a payment through the Payment Link. The Integrator sets the `expiryDate` when creating the Payment Link. | | `flowUrl` | The Payment Link that the payer can be redirected to in order to make a payment attempt. | | `status` | The up-to-date status of the Payment Link. The status can be: ACTIVE - The Payment Link is active and ready to be used for a payment attempt. SUCCEEDED - A payment has already succeeded using this Payment Link. You can no longer make another payment attempt using it. EXPIRED - The Payment Link has expired, which means the date set by the Integrator in the `expiryDate` has passed. You can no longer make another payment attempt using it. | ## Payment Attempt Details {#payment-attempt-details} The [Get payment link payments](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md#getPaymentLinkPayments) endpoint returns the details of the payment attempts made through a Payment Link, in ascending order by creation date. Use the status of each attempt to understand whether a payment has succeeded. | **Field** | **Description** | |---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `paymentId` | The ID of the payment. Use this with the [Get payment](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md#getPayment) endpoint to fetch the details of this particular payment. | | `providerId` | The ID assigned to the payer's bank by Mastercard Open Finance. This is either populated in the Create payment link request, or selected by the payer during the authorization flow. | | `context` | This generally includes the data populated in the Create payment link request. If you do not provide it, some of the data can be populated from the configurations you made during onboarding. See the Onboarding Guide for details. | | `providerPaymentId` | The ID of the payment as assigned by the bank. | | `status` | The latest internal status. This can also include the date and time of the latest status and an array of previous statuses. Refer to the [Payment Status Model](https://developer.mastercard.com/ob-accept-payments/documentation/payments/payment-status-model/index.md) for interpretation. | ## Example Flow {#example-flow} The following screens show an example of the payer journey. These are for reference only. Your actual implementation may differ. **Example of a bill with a payment link which can be presented to the payer** ![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/PL_ref_1i.png) **Mastercard Open Finance Pay screens** ![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/PL_ref_1ii.png) ![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/PL_ref_1iii.png) **Example of ASPSP screens (as per UK Test Bank)** ![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/PL_ref_1iv.png) ![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/PL_ref_1v.png) ![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/PL_ref_1vi.png) **Mastercard Open Finance Pay screens** ![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/PL_ref_1vii.png) **Example of a bill screen that the payer can be returned to after payment** ![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/PL_ref_1viii.png)