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 MUST set a payment-amount and a destination address known as the creditor. There are three creditor-types to choose from:

  1. A Sort Code and Account Number (SCAN).
  2. A payee.
  3. A Griffin bank account url.

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 'PUT' \
  -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"
}

At this point funds have been debited from your account, so you will also receive a transaction-created event. If payment processing fails, the funds will be credited back to your account.

{
    "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"
}