Skip to main content

Make a payment

This guide will walk you through making a payment to a UK bank account. Payment processing is a multi-step process which requires interacting with several resource types. Learn about payments, transactions, submissions and admissions here

Prerequisites​

You have already set up a bank account to make the payment from - if you haven’t, you can learn more about bank accounts here.

Overview​

There are three steps to making a payment:

  1. Create a payment.
  2. Submit the payment.
  3. Track the submission.

there are two approaches to tracking submissions:

  1. Create a webhook and listen for submission events.
  2. Poll the submission resource.

The sequence diagram below captures the payment submission lifecycle using webhooks.

caution

Webhook events may be sent out of order.

Create a payment​

When creating a payment, you need to set the payment-amount and the creditor. The creditor is the account the payment will be sent to.

You have the option to set a payment-reference to identify or categorise the payment. This is limited to 35 characters.

info

If you don't supply a payment-reference, it will default to "Sent from X", where X is the legal person who owns the account. This will be the entity-name or business-name for companies, or the given-name and surname for individuals. This is also subject to a 35 character limit, so longer names may be cut off.

Next, choose your creditor-type:

  1. Sort code and account number (SCAN).
  2. A payee.
  3. A Griffin bank account.

For the creditor:

  • Set the creditor-type to "uk-domestic".
  • Set the account-number to that of the account you're sending money to.
  • Set the account-number-code to "bban".
  • Set the bank-id to the sort code of the account you're sending money to.
  • Set the bank-id-code to "gbdsc".
  • Set the account holder to the name on the account that you're sending money to.
caution

Dashes are not currently accepted in sort codes.

For the payment-amount:

  • Set the amount to your desired amount.
  • Set the currency to "gbp".
curl "https://api.griffin.com/${BANK_ACCOUNT_PAYMENTS_URL}" \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
  --data '
{
  "creditor": {
    "creditor-type": "uk-domestic",
    "account-number": "35890906",
    "account-number-code": "bban",
    "bank-id": "000000",
    "bank-id-code": "gbdsc",
    "account-holder": "John Doe"
  },
  "payment-amount": {
    "currency": "GBP",
    "value": 20.00
  }
}'

A successful response indicates that an "outbound-payment" has been created. At this point the payment is recorded in our system, but no movement of funds has occurred. To send the payment for processing, you must submit it using the returned payment-submissions-url.

{
  "creditor": {
    "creditor-type": "uk-domestic",
    "account-holder": "John Doe",
    "account-number": "35890906",
    "account-number-code": "bban",
    "bank-id": "000000",
    "bank-id-code": "gbdsc"
  },
  "payment-submissions-url": "/v0/payments/pm.hSJXUxRZT7KGzVrn1bAAdg/submission",
  "payment-amount": {
    "currency": "GBP",
    "value": "20.00"
  },
  "payment-direction": "outbound-payment",
  "created-at": "2023-11-20T16:11:48.283Z",
  "debtor": {
    "account-holder": "Funds",
    "account-number": "97144921",
    "account-number-code": "bban",
    "bank-id": "000000",
    "bank-id-code": "gbdsc",
    "account-url": "/v0/bank/accounts/ba.2Xmn1OCvTzGvC-SmWx2Zrg"
  },
  "payment-url": "/v0/payments/pm.hSJXUxRZT7KGzVrn1bAAdg"
  }

Submit the payment​

To submit the payment for processing, create a new submission using the payment-submissions-url from the response above.

Optionally you can set a payment-scheme. If no value is provided for payment-scheme, then the payment will be routed via FPS.

caution

Payment schemes may apply a limit to the amount that a single payment may transfer. Griffin will reject your payment submission if the amount in the payment you are trying to submit exceeds the chosen payment scheme's limit.

For FPS, the limit is 1,000,000.00 GBP.

curl 'https://api.griffin.com${PAYMENT_SUBMISSION_URL}' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"\
  --data '
  {}
info

You must send a request body, even if it is the empty object.

A successful response contains a submission-url that you can query to track the submission-status. Initially the submission-status is processing which indicates that funds still haven't moved.

{
  "submission-url": "/v0/submissions/ps.nsy0zkWEXlWecCgoRsUuug",
  "submission-scheme-information": {
    "payment-scheme": "fps",
    "end-to-end-identification": "24NENI24TROEBLRUOB55DD6P2E"
  },
  "created-at": "2023-11-22T17:01:54.359Z",
  "submission-status": "processing",
  "payment-url": "/v0/payments/pm.ssvMhtYTTc6DTyX_R1kM4A"
}

Track the submission​

Payment processing is asynchronous. Once you have triggered processing by creating a submission you have two options for tracking that submission until the payment is delivered.

  1. Listen to events sent to your webhook.
  2. Poll the submission.

After creating the submission you will initially receive a submission-created event.

{
    "event-url": "/v0/events/ev._GXe6VjtU-ykVVAbjMt2oQ",
    "event-type": "submission-created",
    "event-payload": {
        "created-at": "2023-11-22T17:10:42.021Z",
        "payment-url": "/v0/payments/pm.ssvMhtYTTc6DTyX_R1kM4A",
        "submission-scheme-information": {
            "end-to-end-identification": "HEHYFKNFNRNW3OEN4W3KDEPDCU",
            "payment-scheme": "fps"
        },
        "submission-status": "processing",
        "submission-url": "/v0/submissions/ps.hnj5b1cHV9a5ezf0Zcjt_A"
    },
    "created-at": "2023-11-22T17:10:42.021Z"
}

If your payment is a future dated payment, you will propmptly receive a submission-updated event with submission-status set to scheduled; payment processing will pause at this point as dictated by the withdrawal schedule. Otherwise, the payment will be processed immediately, the funds will be debited from your account, and you will receive a transaction-created event.

{
    "event-url": "/v0/events/ev.r9EERwzIVVWzjTwcPe2pgA",
    "event-type": "transaction-created",
    "event-payload": {
        "account-url": "/v0/bank/accounts/ba.Hdq7jeJvQomDbMFWfojj3A",
        "balance-change": {
            "currency": "GBP",
            "value": "20.00"
        },
        "account-transaction-url": "/v0/bank/transactions/tr.itUux2E-Uqy18hUSeAkxBQ",
        "account-balance": {
            "currency": "GBP",
            "value": "1940"
        },
        "transaction-origin-type": "payment",
        "balance-change-direction": "debit",
        "post-datetime": "2023-11-22T17:10:42.223Z",
        "payment-url": "/v0/payments/pm.ssvMhtYTTc6DTyX_R1kM4A"
    },
    "created-at": "2023-11-22T17:10:42.021Z"
}

If payment processing succeeds you will receive a submission-updated event where submission-status is delivered. At this point the debit of funds from your account is confirmed and they are unlikely to be credited back.

{
    "event-url": "/v0/events/ev.xApuTv4iWpOEYlYXENVdnA",
    "event-type": "submission-updated",
    "event-payload": {
        "created-at": "2023-11-22T17:10:42.021Z",
        "payment-url": "/v0/payments/pm.ssvMhtYTTc6DTyX_R1kM4A",
        "submission-scheme-information": {
            "end-to-end-identification": "HEHYFKNFNRNW3OEN4W3KDEPDCU",
            "payment-scheme": "fps"
        },
        "submission-status": "delivered",
        "submission-url": "/v0/submissions/ps.hnj5b1cHV9a5ezf0Zcjt_A"
    },
    "created-at": "2023-11-22T17:10:42.021Z"
}

Payment processing may fail, in which case you will receive a submission-updated event where submission-status is set to failed. Failure can occur due to insufficient funds in the account or an invalid sort code and account number combination, for example. If funds were debited from the account during payment processing, they will be credited back upon failure.