# Payment Links source: https://developer.mastercard.com/ob-accept-payments/documentation/features/payment-links/index.md The Payment Links feature enables you to accept one-off payments using a long lived Payment Link directly from your Consumers bank accounts through a simple and secure flow. Unlike commercial Variable Recurring Payments (cVRPs), the consumer needs to authorise with their bank by going through an SCA each time a payment is created. Follow the steps below to create a new Payment Link. #### STEP 1 - Authenticate with the API {#step-1---authenticate-with-the-api} To use the API, you need to be authenticated with the service. You need to ensure that you are using the **ob_accept_payments** scope in the request body when Authenticating. Refer to [Authentication](https://developer.mastercard.com/ob-accept-payments/documentation/developer-support/api-basics/authentication/index.md) for detailed instructions regarding how you can authenticate with the service. #### STEP 2 - Onboard a payment destination {#step-2---onboard-a-payment-destination} As part of the onboarding you will provide the details of the bank account where the payments will be made - the destination. After onboarding an account you will receive an identifier to be used in API calls as the `destinationId`. Note: Depending on your context, in case you are using our PISP license for example, the onboarding may include steps necessary to satisfy Anti-Money-Laundering (AML) regulations and Know-Your-Customers (KYC) requirements. The destination will not be usable to create payments before the completion of the process. #### STEP 3 - Create a Payment Link {#step-3---create-a-payment-link} After the initial onboarding, and authentication, you are ready to call the Create Payment 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. There are a few important options when creating a Payment Link: | **Parameter** | **Description** | |-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `paymentRail` | This defines the payment rails that will be used by the consumer's bank to execute the payment. This will impose certain restrictions to the API request and the flow. See [Payment Rails](https://developer.mastercard.com/ob-accept-payments/documentation/developer-support/event-notifications/event-notifications/index.md) for more details. | | `destinationId` | Refer to your onboarding data. This is the ID of your onboarded receiving account. Note that your account may have a different ID depending on the environment. | | `redirectUrl` | The URL, on your side, where the consumer is taken to upon completion of the flow. Note: this URL needs to be allowlisted so should also be provided in the onboarding data we receive from you. | | `expiryDate` | Sets the date that the newly created Payment Link will expire. After the date set in the `expiryDate` in the Create payment link request, you will no longer be able to accept a payment via that Payment Link. It is important to ensure that you set an expiry date that is long enough for your customers to react to. | | `context` | The context in which the payment is made. For UKFasterPayments rail, it is strongly recommended to populate the data in this section, as this may be required for the risk assessment performed by the banks. See [Payment Rails](https://developer.mastercard.com/ob-accept-payments/documentation/developer-support/event-notifications/event-notifications/index.md) for more details. | After successfully creating the payment internally, we will reply with: * A `flowUrl`, which will be used in the next step. * A `paymentLinkId`, which can be used to fetch the Payment Link status (Step 5) and to fetch the payments that have been attempted using the Payment Link (Step 6). #### STEP 4 - Redirect the Consumer to Payment Authorization flow {#step-4---redirect-the-consumer-to-payment-authorization-flow} The next step is to redirect the Consumer to the flowUrl and start the payment authorization flow. The link is long-lived. However, it is only valid until the date defined in the `expiryDate`. Once the Payer navigates to the authorization link, they will be presented with a choice of banks and they will be able to authorize the payment. After going through the authorisation flow, the Payer will be sent back to the redirect URL you provided when creating the Payment Link. Note: Unlike Single Immediate Payments, the payer can retry this authorization link if it fails. Once there has been a successful payment attempt using the Payment Link, another payment cannot be made using that Payment Link. The Integrator can see all of the Payment Link' payment attempts by calling `/payment-links/{payment_link_id}/payments`, where payment attempts are returned in ascending order by creation date. An example of the flow is shown below. These are for reference only. The actual implementation may differ. **Example of a bill with a payment link which can be presented to the PSU** ![](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 PSU can be returned to after payment** ![](https://static.developer.mastercard.com/content/ob-accept-payments/uploads/PL_ref_1viii.png) #### STEP 5 - Request details of a Payment Link {#step-5---request-details-of-a-payment-link} Immediately after creating the Payment it becomes possible to query the status of the Payment Link using the Get payment link endpoint. `The paymentLinkId`, received at step 3, is required to fetch the Payment Link details and status. It is recommended to only use this endpoint after receiving a *PaymentLinkStatusUpdated* webhook to reduce your infrastructure requirements. API Reference: `GET /payment-links/{payment_link_id}` The details that will be returned when you call the Get payment link endpoint: | **Field** | **Description** | |------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `paymentRequest` | The details that were used for the creation of the Payment using the Payment Link. These will reflect the values passed in the payment object from the Create payment link request. | | `createdDate` | The date that the Payment Link was created in the Mastercard Open Finance Pay system. | | `expiryDate` | The date that the Payment Link will expire. After this date it will no longer be possible to attempt a payment using the Payment Link. The `expiryDate` is set by the Integrator when creating the Payment Link. | | `flowUrl` | The Payment Link that the PSU can be redirected 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 successful payment has already been achieved using this Payment Link. It is no longer possible to make another payment attempt using this Payment Link.\| EXPIRED - The Payment Link has expired meaning the date set by the Integrator in the expiryDate has passed. It is no longer possible to make another payment attempt using this Payment Link. | #### STEP 6 - Request details of a Payment attempt using the Payment Link {#step-6---request-details-of-a-payment-attempt-using-the-payment-link} Unlike links returned for Single Immediate Payments, Payment Links are long lived and can support multiple payment attempts and can be sent to the PSU while the PSU is not in session. For example, a Payment Link can be emailed inside a Bill that is to be paid. As a result, it is important to stay aware of payment attempts that have been made using the Payment Link. Mastercard Open Finance Pay offers a Get payment link payments endpoint to support this. With this endpoint, the Integrator can use the `paymentLinkId` (received at step 3) to fetch the details of the payment attempts using the Payment Link and to understand the up to date status of each payment attempt. It is recommended to use the endpoint after receiving a *PaymentLinkPaymentAttempted* webhook to reduce your infrastructure requirements. API Reference: `GET /payment-links/{payment_link_id}/payments` This endpoint will return the details of the payment attempts that have been made using a Payment Link. The payments will be shown in order of their createdDate in ascending order. With this endpoint you can see the status of a payment to understand if there has been a successful payment attempt. You can also fetch the paymentId which can be used with the Get payment endpoint \[/payments/{payment_id}\] to request the details of that particular payment attempt. | **Field** | **Description** | |---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `paymentId` | The ID of the payment. This can be used in the Get payment endpoint to fetch the details of this particular payment. | | `providerId` | The ID assigned to the Consumer's bank by MCOBS. This is either populated in the Create Payment request, or selected by the Consumer during the authorization flow. | | `context` | This will generally include the data populated in Create Payment request. If not provided, some of the data can be populated from the configurations made during onboarding. See the Onboarding Guide for details. | | `providerPaymentId` | This is the ID of the payment as assigned by the bank. | | `status` | This will include the latest internal status. Please check Payment Status Model in Resources for interpretation. This can also include the date and time of the latest status and an array of previous statuses. | #### STEP 7 - Process webhook notifications for Payment status {#step-7---process-webhook-notifications-for-payment-status} We recommend you use the Mastercard Open Finance Pay webhooks functionality, instead of polling for the Payment Link status. Webhooks enable you to receive notifications when a Payment Link status changes so that you can avoid repeatedly polling. A webhook notification will be sent when we identify a payment status change. Available notifications include: * **PaymentLinkStatusUpdated** - Triggered when the status of the Payment Link changes. It will include the `paymentLinkId`. When you receive a *PaymentLinkStatusUpdated* webhook you should call the Get payment link endpoint to get the latest status. * **PaymentLinkPaymentAttempted** - Triggered when a new payment is attempted using the Payment Link. This will include the `paymentLinkId` and the `paymentId`. When you receive a *PaymentLinkPaymentAttempted* webhook you should call the Get payment link payments endpoint to get the details of the payment attempts made using the Payment Link. When you receive a *PaymentLinkPaymentAttempted* webhook you should be prepared for receiving webhooks on the new `paymentId` and keep track that this new payment is related to this payment link. You can also use this `paymentId` to call the Get payment endpoint to fetch the details for that particular payment. See [Webhooks](https://developer.mastercard.com/ob-accept-payments/documentation/developer-support/event-notifications/event-notifications/index.md) for details about the body of the message, security, and how it needs to be processed. #### STEP 7 - Present the payment status to the customer {#step-7---present-the-payment-status-to-the-customer} When the Consumer completes the Payment Authorization flow, they are redirected back to the *redirectUrl* you provided when creating the Payment Link. Mastercard Open Finance Pay appends an extra query parameter `?paymentId=`, where `` is the same ID you got from step 6 or in the *PaymentLinkPaymentAttempted* webhook. You can use this parameter to match with any *AcceptPaymentStatusUpdated* webhook notifications and subsequent Get Payment calls you made to determine what to present to the user. For security reasons, it is recommended to always check that the `paymentId` matches the one you obtained in step 6 or in the *PaymentLinkPaymentAttempted* webhook, since browsers allow their users to manipulate any query parameters. See the [Payment Status Model](https://developer.mastercard.com/ob-accept-payments/documentation/payments/single-immediate-payments/payment-status-model/index.md) section for a description of all the statuses a payment can be in. See details on how to handle the failure and non-usable states in the [Codes and Formats](https://developer.mastercard.com/ob-accept-payments/documentation/developer-support/code-and-formats/index.md) section.