Receive a book transfer

This guide will walk you through receiving a book transfer to one of your accounts. Payment processing is a multi-step process which requires interacting with several resource types. Learn about payments, transactions, submissions and admissions here

This guide covers receipt of a book transfer, view our other guide to learn about sending book transfers.

Prerequisites

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

info

If you are attempting to receive a payment into a pooled account, the account must first have one or more pooled account members added to it. You can view the guide to add pooled account members here.

Receive a book transfer

We recommend creating a webhook in order to receive notifications of new inbound payments. The examples below illustrate a typical set of notifications that you will receive for an inbound book transfer.

The payment-created event informs you that an inbound payment has been received.

{
    "event-url": "/v0/events/ev.MG7WpgsiWrqVlfQlYnwZ3w",
    "event-type": "payment-created",
    "event-payload": {
        "created-at": "2023-12-12T14:46:03.706Z",
        "creditor": {
            "account-url": "/v0/bank/accounts/ba.bihSK9VMQRCVhrFm5Rv7MA",
            "creditor-type": "griffin-bank-account"
        },
        "debtor": {
            "account-holder": "Jane Doe",
            "account-number": "60484240",
            "account-number-code": "bban",
            "bank-id": "000000",
            "bank-id-code": "gbdsc"
        },
        "payment-admissions-url": "/v0/payments/pm.BEPkS5c_XAy9ILoXr4rTYA/admissions",
        "payment-amount": {
            "currency": "GBP",
            "value": "20.00"
        },
        "payment-direction": "inbound-payment",
        "payment-url": "/v0/payments/pm.BEPkS5c_XAy9ILoXr4rTYA"
    },
    "created-at": "2023-12-12T14:46:03.706Z"
}

The admission-created, event can also be used to identify when a payment has been received, the admission-scheme-information indicates the payment-scheme, which in this case is book-transfer. Additionally you can use admissions to monitor the payment as it is being processed.

{
    "event-url": "/v0/events/ev.2mTHGtHNUjSVYgGEGUeuMQ",
    "event-type": "admission-created",
    "event-payload": {
        "admission-scheme-information": {
            "payment-scheme": "book-transfer"
        },
        "admission-status": "processing",
        "admission-url": "/v0/admissions/pa.b-zT_tXrXHO7KkuuRx8eXQ",
        "created-at": "2023-12-12T14:46:03.706Z",
        "payment-url": "/v0/payments/pm.BEPkS5c_XAy9ILoXr4rTYA"
    },
    "created-at": "2023-12-12T14:46:03.706Z"
}

The admission-updated event signals an update to the payment as a result of processing; in this case its status is delivered, signalling that the payment amount has been credited to the recipient, but it could also signal a rejection or return.

{
    "event-url": "/v0/events/ev.y3pDUTezWC-G41Pk0ilYfg",
    "event-type": "admission-updated",
    "event-payload": {
        "admission-scheme-information": {
            "payment-scheme": "book-transfer"
        },
        "admission-status": "delivered",
        "admission-url": "/v0/admissions/pa.b-zT_tXrXHO7KkuuRx8eXQ",
        "created-at": "2023-12-12T14:46:03.706Z",
        "payment-url": "/v0/payments/pm.BEPkS5c_XAy9ILoXr4rTYA"
    },
    "created-at": "2023-12-12T14:46:03.706Z"
}

The transaction-created event also signals that the payment amount has been credited to the recipient. transaction-created events additonally include account-balance information, so they are useful for maintaining an account statement, or for reconcilliation.

{
    "event-url": "/v0/events/ev.mrsba9YxUtaoo4JP5eOv6Q",
    "event-type": "transaction-created",
    "event-payload": {
        "account-balance": {
            "currency": "GBP",
            "value": "20.00"
        },
        "account-transaction-url": "/v0/bank/transactions/tr.PK8zcJ9wVnOn5jHghsNJew",
        "account-url": "/v0/bank/accounts/ba.bihSK9VMQRCVhrFm5Rv7MA",
        "balance-change-direction": "credit",
        "balance-change": {
            "currency": "GBP",
            "value": "20.00"
        },
        "payment-url": "/v0/payments/pm.BEPkS5c_XAy9ILoXr4rTYA",
        "post-datetime": "2023-12-12T14:46:03.978Z",
        "transaction-origin-type": "payment"
    },
    "created-at": "2023-12-12T14:46:03.706Z"
}