Receive a payment

Griffin automatically receives payments on your behalf, so there are no actions you need to take, but you can track their progress. We recommend creating a webhook in order to receive notifications of new inbound payments and to track their status through admissions. The sequence diagram below outlines the payment admission lifecycle:

caution

Webhook events may be sent out of order.

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. 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": "fps"
        },
        "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": "fps"
        },
        "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"
}