Making Bank Payments

🚧

Prerequisites

In order to make payments to UK bank accounts you will need to have created your Griffin user account and confirmed any regulatory permissions.

For the bank payment, you will need a bank account and the following details from the payee:

  • Payee name
  • Sort code
  • Account number

📘

The below documentation assumes you know your API key and organisation ID. These are referred to as $API_KEY and $ORGANISATION_ID in code samples. If you don't have your organisation ID available, refer to Navigating the API

Creating a Payee

Before making a payment, a payee must exist. Payees are associated with legal persons, see Creating a Legal Person.

For the UK banking system this means creating one with a sort code and account number.

curl 'https://api.beta.griffin.sh/v0/legal-persons/$LEGAL_PERSON_ID/bank/payees' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: GriffinAPIKey $API_KEY" \
  --data-binary '{"account-holder":"John Smith","account-number":"05678934","bank-id":"123451"}'

The response will be as below. We're interested in the payee-url as this will be used as the destination for the payment.

{
    "created-at": "2021-11-17T08:19:11.019Z",
    "legal-person-url": "/v0/individuals/lp.RdNWdgRdVXuw3q1wyVuecQ",
    "account-holder": "John Smith",
    "account-number": "05678934",
    "payee-url": "/v0/payees/pe.p2sYdvNxQ6mGXxiYGrBS8A",
    "country-code": "GB",
    "bank-id": "123451",
    "payee-payments-url": "/v0/payees/pe.p2sYsvNmQ6mGXZiYGrBS8A/payments"
}

Making a Payment

Payments are asynchronous: The first request triggers the process, then you can poll to discover the result.

curl 'https://api.beta.griffin.sh/v0/bank/accounts/ac.svcsUO4KS3uz0ChEr5l9zA/payments' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: GriffinAPIKey $API_KEY" \
  --data-binary '{
    "payee-url": "/v0/payees/pe.Hu7vvEX3TPWFjlwvKsb9QA",
    "payment-amount": {
      "currency": "GBP",
      "value": "1234"
    },
    "payment-reference": "Test"
  }'

The response will recognise the payment as an accepted outbound payment, but it will not yet be submitted. At this point, the payment simply exists in the system.

{
    "account-url": "/v0/bank/accounts/ac.svcsUO4KS3uz0ChEr5l9zA",
    "payment-submission-url": "/v0/payments/pm.v-MR5nQSQpmpye4n3tMYUw/submission",
    "payment-reference": "Test",
    "payment-amount": {
        "currency": "GBP",
        "value": "1234.00"
    },
    "payment-direction": "outbound-payment",
    "payment-status": "accepted",
    "created-at": "2021-11-15T15:19:32.794Z",
    "payee-url": "/v0/payees/pe.Hu7vvEX3TPWFjlwvKsb9QA",
    "payment-url": "/v0/payments/pm.v-MR5nQSQpmpye4n3tMYUw"
}

To submit a payment, you must create a submission resource for it. This is simply a PUT request to the payment-submission-url in the response above.

curl 'https://api.beta.griffin.sh/v0/payments/pm.v-MR5nQSQpmpye4n3tMYUw/submission' \
  -X 'PUT' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: GriffinAPIKey $API_KEY"

Monitoring a Payment

The payment response contained a payment-url - this can be used to monitor the status of the payment.

curl 'https://api.beta.griffin.sh/v0/payments/pm.v-MR5nQSQpmpye4n3tMYUw' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: GriffinAPIKey $API_KEY"

If the payment is successfully accepted, payment-status will be accepted:

{
  "account-url": "/v0/bank/accounts/ac.svcsUO4KS3uz0ChEr5l9zA",
  "payment-reference": "Test",
  "payment-amount": {
    "currency": "GBP",
    "value": "1234.00"
  },
  "payment-direction": "outbound-payment",
  "created-at": "2021-11-15T15:19:32.794Z",
  "payee-url": "/v0/payees/pe.p2sYdvNmQ6mGXZiYGrBS8A",
  "payment-url": "/v0/payments/pm.v-MR5nQSQpmpye4n3tMYUw",
  "payment-status": "accepted"
}