Payee Management

The Moneyhub payments API is designed to be used to allow payments from arbitrary accounts to a single trusted account. For example a merchant or charity may want to enable their customers to pay into their bank account.

For this reason we require the receiving account to be pre-registered with us as a “payee”. We allow this to be done via API.

It is worth noting that some banks have limits on the length of payee name and the characters used. We recommend you keep your payee name (name) within the following limits - 18 characters, supported characters - /^[a-zA-Z0-9\s&]+$/

When creating payees via API the steps are as follows:

Get a client credentials token with the scope payee:create
Create a payee using the POST /payees route
You will receive back an id for the payee. This can be used in subsequent flows

API Reference

POST /payees

Example request using moneyhub api client

const tokens = await moneyhub.addPayee({
  accountNumber: "your account number",
  sortCode: "your sort code",
  name: "name of Payee", // max 256 charcaters
})

Example request

curl --request POST \
--url https://identity.moneyhub.co.uk/payees \
--header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkQ5SkFObVlmU0dfa2J0MktScFRLbzdRQ (... abbreviated for brevity ...)' \
--header 'content-type: application/json' \
--data '{\n   "sortCode": "123456",\n "accountNumber": "12345678",\n  "name": "Account name"\n}'

Example response

{
    "data": {
        "id": "e07f8dca-1a79-440a-8667-8cd02a000559",
        "externalId": "",
        "clientId": "c40d7f7a-a698-4bf1-84bf-8f3798c018b2",
        "sortCode": "123456",
        "accountNumber": "12345678",
        "createdAt": "2019-05-23T07:48:53.916Z",
        "modifiedAt": "2019-05-23T07:48:53.916Z",
        "active": true,
        "name": "Account name"
    },
    "meta": {}
}

This route requires an access token from the client credentials grant with the scope of payee:create.

It creates a payee that later can be used to initiate a payment.

GET /payees

Example request using moneyhub api client

const tokens = await moneyhub.getPayees({
	limit: "limit", // optional
  offset: "offset", // optional
})

Example request

curl --request GET \
--url https://identity.moneyhub.co.uk/payees \
--header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkQ5SkF (... abbreviated for brevity ...)'

Example response

{
    "data": [
        {
            "id": "e07f8dca-1a79-440a-8667-8cd02a000559",
            "clientId": "c40d7f7a-a698-4bf1-84bf-8f3798c018b2",
            "sortCode": "123456",
            "accountNumber": "12345678",
            "createdAt": "2019-05-23T07:48:53.916Z",
            "modifiedAt": "2019-05-23T07:48:53.916Z",
            "active": true,
            "name": "Account name"
        }
    ],
    "meta": {}
}

This route requires an access token from the client credentials grant with the scope of payee:read.

It returns all the payees that have been created for an specific API client.

Query Parameters	Type	Description
limit	number	Set the number of records to be retrieved (Default: 10)
offset	number	By specifying offset, you retrieve a subset of records starting with the offset value (Default: 0)