Create a payee

A payee stores the details of someone you want to send money to - this could be an individual, joint account holders, or a business. Similar to saving a contact, once you've saved someone as a payee, you can easily make future payments to them without re-entering their information.

Payees are linked to legal persons, not accounts. This means all accounts tied to a legal person share the same list of payees.

For UK accounts, you need to store:

• The payee's name
• Their sort code (the bank identifier)
• Their account number

You can work with payees in two ways:

• Through our API if you want to integrate payees into your platform
• Through our app

caution

Dashes are not currently accepted in sort codes.

Creating a payee

You need the following details to create a payee.

• Payee name: account-holder - this could be an individual, two named individuals on a joint account or a business name
• Account number: account-number
• Sort code: bank-id

You will also need the legal person URL for the legal person you want to create the payee for. This is shown in the example as $LEGAL_PERSON_URL.

curl "https://api.griffin.com${LEGAL_PERSON_URL}/bank/payees" \
  -H 'Content-Type: application/json' \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
  --data '
{
  "account-holder": "John Doe"
  "account-number": "35890906",
  "bank-id": "000000"
}'

info

The payee is associated with the legal person rather than the individual bank account. This is because a single customer may have multiple bank accounts from which they want to make payments to that payee.

A successful response looks like this:

{
  "created-at": "2023-11-22T16:58:52.899Z",
  "legal-person-url": "/v0/legal-persons/lp.us731F0aUVecywxJo_7UAA",
  "account-holder": "John Doe",
  "account-number": "35890906",
  "payee-url": "/v0/payees/pe.C3xD5WV0QOWVZ7lNFoQaUQ",
  "country-code": "GB",
  "bank-id": "000000",
  "payee-status": "active",
}

The payee-url is the creditor for the payment, so you’ll need it for when you go on to make a payment

Attaching a Confirmation of Payee request

If you have run a Confirmation of Payee check on the details that you want to create a payee for, you'll need to include a reference to the CoP check when creating a payee. This can be done by including the CoP request URL in the Create Payee request.

Here's what a request might look like:

curl "https://api.griffin.com${LEGAL_PERSON_URL}/bank/payees" \
  -H 'Content-Type: application/json' \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
  --data '
{
  "account-holder": "John Doe"
  "account-number": "35890906",
  "bank-id": "000000",
  "cop-request-url": "https://..."
}'

The response will include the CoP URL as a property of the payee.

Here's what a response might look like:

{
  "cop-request-url": "https://...",
  "created-at": "2023-11-22T16:58:52.899Z",
  "legal-person-url": "/v0/legal-persons/lp.us731F0aUVecywxJo_7UAA",
  "account-holder": "John Doe",
  "account-number": "35890906",
  "payee-url": "/v0/payees/pe.C3xD5WV0QOWVZ7lNFoQaUQ",
  "country-code": "GB",
  "bank-id": "000000",
  "payee-status": "active",
}