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.

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)