Introduction

A pay link is a unique URL that allows users to make payments seamlessly via the Pay Link Widget. By creating a pay link, you provide an easy way for others to transfer money to a specified account. This document guides you through the necessary steps to create a pay link using the MoneyHub API.

Prerequisites

General Requirements

Ensure you have the following setup before proceeding:

• You have an Admin Portal User
• You have created an API Client with pay_link:create and pay_link:read scopes enabled.
• You have created a Pay Link Widget in the Admin Portal
• You have installed the moneyhub-api-client library (optional)

Obtain Access Token

Before creating a pay link, you need to obtain an access token. Follow our authentication guide to get a client credentials token and make sure you set it with the pay_link:create scope.

Note: If you also wish to access the pay links later on, include pay_link:read scope as well.

Obtain payeeId

To create a pay link, you will need a payeeId. You can create a payee programmatically using the Payee Management API.

Note: If you do not have a payeeId, you can optionally pass in payee details directly when creating the pay link (described below).

Create a Pay Link

With the access_token and payeeId obtained, you can now create a pay link using the /pay-links endpoint.

Request

Endpoint

POST <https://identity.moneyhub.co.uk/pay-links>

Headers

Content-Type: application/json  
Authorization: Bearer YOUR_ACCESS_TOKEN

Body

{  
  "widgetId": "b6393c9b-2f9f-4a12-a3b0-da8b0d3c6f8a",  
  "payeeId": "a5c2394d-f1bb-4f8f-98fb-65cf2c4d087c", 
  "reference": "slytherin",  
  "amount": 1500,  
  "endToEndId": "Hogwards-2024",  
  "useOnce": true,  
  "expiresAt": "2021-02-01T11:08:45.574Z"  
}

Properties

📘

Optionally Pass in Payee Details Directly

If you do not have an existing payeeId created via our API, you can pass in payee details instead and we will create a new payee. This approach can be useful for testing but is not recommended for ongoing use.

JSON

{  
  "widgetId": "b6393c9b-2f9f-4a12-a3b0-da8b0d3c6f8a",  
  "payee": {
      "accountNumber": "88888888",
      "sortCode": "666666",
      "name": "Harry Potter",
    },, 
  "reference": "slytherin",  
  "amount": 1500,  
  "endToEndId": "Hogwards-2024",  
  "useOnce": true,  
  "expiresAt": "2021-02-01T11:08:45.574Z"  
}

 Example using cURL

curl -X POST '<https://identity.moneyhub.co.uk/pay-links'>  
-H 'Content-Type: application/json'  
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'  
-d '{  
  "widgetId": "b6393c9b-2f9f-4a12-a3b0-da8b0d3c6f8a",  
  "payeeId": "a5c2394d-f1bb-4f8f-98fb-65cf2c4d087c",  
  "reference": "slytherin",  
  "amount": 1500,  
  "endToEndId": "Hogwards-2024",  
  "useOnce": true,  
  "expiresAt": "2021-02-01T11:08:45.574Z"  
}'

Example using moneyhub-api-client

const payLinkData = await moneyhub.addPayLink({
  widgetId: "b6393c9b-2f9f-4a12-a3b0-da8b0d3c6f8a",
  payeeId: "a5c2394d-f1bb-4f8f-98fb-65cf2c4d087c",
  reference: "slytherin",
  amount: 1500,
  endToEndId: "Hogwards-2024",
  useOnce: true,
  expiresAt: "2021-02-01T11:08:45.574Z"
});

Response

A successful response will contain details of the newly created pay link:

{  
  "id": "6db2f995-6a8d-4929-aafb-1989b2d5f72b",  
  "widgetId": "b6393c9b-2f9f-4a12-a3b0-da8b0d3c6f8a",  
  "payeeId": "a5c2394d-f1bb-4f8f-98fb-65cf2c4d087c",  
  "reference": "slytherin",  
  "amount": 1500,  
  "endToEndId": "Hogwards-2024",  
  "useOnce": true,  
  "expiresAt": "2021-02-01T11:08:45.574Z",  
  "createdAt": "2021-01-01T12:00:00.000Z",  
  "updatedAt": "2021-01-01T12:00:00.000Z"  
}

Using the Pay Link

To use the pay link, add the payLinkId to your widget parameters upon initialisation. For demo purposes, you can visit:

https://identity.moneyhub.co.uk/widget-pages/PAY_LINK_WIDGET_ID#payLinkId=PAY_LINK_ID

For further details on initialising the widget, refer to the General Widget Configuration section.

With a pay link widget, you can then visit:

BASE_URL/widget-pages/PAY_LINK_WIDGET_ID#payLinkId=PAY_LINK_ID

This allows users to easily make payments as per the created link details. Ensure you store these details securely for future reference and usage.