Skip to main content

Open an embedded account

An embedded account enables you to offer a real bank account to your customers. Learn more about embedded accounts.

Prerequisites​

  • You will need your organization-bank-accounts-url (shown as $ORGANIZATION_BANK_ACCOUNTS_URL in the examples below). Your organization-bank-accounts-url is one of the URLs returned when you request your organization-url. If you don't have your organization-url yet, check out our getting started guide.

Request​

  • Set the bank-product-type to embedded-account
  • Set the owner-url to the legal person URL who is entitled to the money in the account
note
  • The beneficiary and owner are the same legal person.
curl "https://api.griffin.com${ORGANIZATION_BANK_ACCOUNTS_URL}" \
  -X 'POST' \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '
{
  "bank-product-type": "embedded-account",
  "owner-url": "$CUSTOMER_LEGAL_PERSON_URL"
}'

Synchronous Response​

A successful response look like this.

{
    "account-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A",
    "pooled-funds": false,
    "available-balance": {
        "currency": "GBP",
        "value": "0.00"
    },
    "account-restricted": false,
    "display-name": "embedded-1",
    "beneficiary-url": "$CUSTOMER_LEGAL_PERSON_URL",
    "account-balance": {
        "currency": "GBP",
        "value": "0.00"
    },
    "account-transactions-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/transactions",
    "created-at": "2023-12-07T17:03:20.757Z",
    "account-payments-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/payments",
    "bank-product-type": "embedded-account",
    "bank-addresses": [],
    "owner-url": "$CUSTOMER_LEGAL_PERSON_URL",
    "close-account-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/actions/close",
    "account-admissions-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/admissions",
    "account-status": "opening",
    "account-submissions-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/submissions",
    "controller-url": "/v0/legal-persons/lp.Ph9xPUvzULGohmZ4_u_TDw"
}

This response indicates that you have successfully requested the creation of a new embedded account. The account-status will likely be opening since their 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.IcqDdMDxT7OaYRznoit-7A",
    "pooled-funds": false,
    "available-balance": {
        "currency": "GBP",
        "value": "0.00"
    },
    "account-restricted": false,
    "display-name": "embedded-1",
    "beneficiary-url": "$CUSTOMER_LEGAL_PERSON_URL",
    "account-balance": {
        "currency": "GBP",
        "value": "0.00"
    },
    "account-transactions-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/transactions",
    "created-at": "2023-12-07T17:03:20.757Z",
    "account-payments-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/payments",
    "bank-product-type": "embedded-account",
    "bank-addresses": [],
    "owner-url": "$CUSTOMER_LEGAL_PERSON_URL",
    "close-account-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/actions/close",
    "account-admissions-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/admissions",
    "account-status": "open",
    "account-submissions-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/submissions",
    "controller-url": "/v0/legal-persons/lp.Ph9xPUvzULGohmZ4_u_TDw"
}