Open a safeguarding account
A safeguarding account is for managing your customers funds. Only firms regulated as Electronic money institutions (EMIs) and payments institutions (PIs) in the UK can open safeguarding accounts. You can choose to open a dedicated account for each of your customers, or a pooled account for holding funds from multiple customers. Learn more about bank accounts.
Prerequisites
You will need your
organization-bank-accounts-url
(shown as$ORGANIZATION_BANK_ACCOUNTS_URL
in the examples below). Yourorganization-bank-accounts-url
is one of the URLs returned when you request yourorganization-url
. If you don't have yourorganization-url
yet, check out our getting started guide.Before you can open an account for a customer, you must determine the legal relationship that your customer has with the account. Learn about owners, controllers and beneficiaries. Any named owner or beneficiary will need to be onboarded. Check out our guides for onboarding customers.
- Dedicated safeguarding accounts
- Pooled safeguarding accounts
Request
- Set the
bank-product-type
tosafeguarding-account
. - Set
pooled-funds
tofalse
. - Set the
beneficiary-url
to the legal person URL who is entitled to the money in the account. - Optionally, pick a
display-name
for the account.
If you are opening the account on behalf of an Electronic Money Institution (EMI) or Payment Institution (PI) set the owner-url
to the legal person URL representing that institution. By default, you will be the owner.
The beneficiary-url
and owner-url
cannot be the same legal person.
The example below shows a dedicated safeguarding account, where $OWN_LEGAL_PERSON_URL
is your organisation's legal person URL, and $CUSTOMER_LEGAL_PERSON_URL
is your customer's legal person URL.
curl "https://api.griffin.com${ORGANIZATION_BANK_ACCOUNTS_URL}" \
-X 'POST'
-H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
-H 'Content-Type: application/json' \
--data '
{
"display-name": "Jennifer Daly",
"bank-product-type": "safeguarding-account",
"beneficiary-url": "$CUSTOMER_LEGAL_PERSON_URL",
"pooled-funds": false
}'
Synchronous Response
A successful response looks like this.
{
"account-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g",
"pooled-funds": false,
"display-name": "Jennifer Daly",
"beneficiary-url": "$CUSTOMER_LEGAL_PERSON_URL",
"owner-url": "$OWN_LEGAL_PERSON_URL",
"controller-url": "$OWN_LEGAL_PERSON_URL",
"account-balance": {
"currency": "GBP",
"value": "0.00"
},
"available-balance": {
"currency": "GBP",
"value": "0.00"
},
"account-transactions-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g/transactions",
"created-at": "2023-10-16T13:34:17.771Z",
"account-payments-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g/payments",
"bank-product-type": "safeguarding",
"bank-addresses": [],
"close-account-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g/actions/close",
"account-status": "opening"
}
This response indicates that you have successfully registered your intent to open a dedicated safeguarding account, where your customer is the beneficiary, and your organisation is both the owner and controller. The account-status
will likely be opening
since there are some background preparatory tasks that need to finish befoe the account can be used. These take place automatically, so you can simply poll the account-url
endpoint until the account-status
is open
.
NOTE: If you have created a webhook for your
organisation you can also listen
for the account-status-updated
webhook event and track account-status
.
Learn more about the account lifecycle.
Poll for status
Poll the account-url
endpoint.
curl "https://api.griffin.com${ACCOUNT_URL}" \
-X 'GET' \
-H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
-H 'Content-Type: application/json' \
When the account-status
is open
, the account is ready for use.
{
"account-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g",
"pooled-funds": false,
"display-name": "Jennifer Daly",
"beneficiary-url": "$CUSTOMER_LEGAL_PERSON_URL",
"owner-url": "$OWN_LEGAL_PERSON_URL",
"controller-url": "$OWN_LEGAL_PERSON_URL",
"account-balance": {
"currency": "GBP",
"value": "0.00"
},
"available-balance": {
"currency": "GBP",
"value": "0.00"
},
"account-transactions-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g/transactions",
"created-at": "2023-10-16T13:34:17.771Z",
"account-payments-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g/payments",
"bank-product-type": "safeguarding",
"bank-addresses": [],
"close-account-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g/actions/close",
"account-status": "open"
}
Request
- Set the
bank-product-type
tosafeguarding-account
. - Set the
pooled-funds
field totrue
. - Optionally, pick a
display-name
for the account.
- You cannot set the
beneficiary-url
for pooled accounts, as the funds belong to multiple customers. - Before a pooled safeguarding account is able to make or receive payments, you must add pooled members to the account
If you are opening the account on behalf of an Electronic Money Institution (EMI) or Payment Institution (PI) set the owner-url
to the legal person URL representing that institution. By default, you will be the owner.
The example below shows a pooled safeguarding account, where $OWN_LEGAL_PERSON_URL
is your organisation's legal person URL.
curl "https://api.griffin.com${ORGANIZATION_BANK_ACCOUNTS_URL}" \
-X 'POST'
-H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
-H 'Content-Type: application/json' \
--data '
{
"display-name": "Customer Digital Wallets",
"bank-product-type": "safeguarding-account",
"pooled-funds": true
}'
Synchronous Response
A successful response looks like this.
{
"account-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g",
"pooled-funds": true,
"display-name": "Customer Digital Wallets",
"owner-url": "$OWN_LEGAL_PERSON_URL",
"controller-url": "$OWN_LEGAL_PERSON_URL",
"account-balance": {
"currency": "GBP",
"value": "0.00"
},
"available-balance": {
"currency": "GBP",
"value": "0.00"
},
"account-transactions-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g/transactions",
"created-at": "2023-10-16T13:34:17.771Z",
"account-payments-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g/payments",
"bank-product-type": "safeguarding",
"bank-addresses": [],
"close-account-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g/actions/close",
"account-status": "opening"
}
This response indicates that you have successfully registered your intent to open a pooled safeguarding account, where your organisation is both the owner and controller, and there is no beneficiary specified. The account-status
will likely be opening
since there are some background preparatory tasks that need to finish before the account can be used. These take place automatically, so you can simply poll the account-url
endpoint until the account-status
is open
.
Learn more about the account lifecycle.
Poll for status
Poll the account-url
endpoint.
curl "https://api.griffin.com${ACCOUNT_URL}" \
-X 'GET' \
-H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
-H 'Content-Type: application/json' \
When the account-status
is open
, the account is ready for use.
{
"account-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g",
"pooled-funds": true,
"display-name": "Customer Digital Wallets",
"owner-url": "$OWN_LEGAL_PERSON_URL",
"controller-url": "$OWN_LEGAL_PERSON_URL",
"account-balance": {
"currency": "GBP",
"value": "0.00"
},
"available-balance": {
"currency": "GBP",
"value": "0.00"
},
"account-transactions-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g/transactions",
"created-at": "2023-10-16T13:34:17.771Z",
"account-payments-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g/payments",
"bank-product-type": "safeguarding",
"bank-addresses": [],
"close-account-url": "/v0/bank/accounts/ba.XsMi7GbNTGy3urMgXXM8_g/actions/close",
"account-status": "open"
}