Receive a payment
This guide will walk you through receiving a payment 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
Prerequisites
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.
Overview
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:
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"
}