Open a EUR or GBP account with its own IBAN

Open one fiat-only EUR or GBP account with an IBAN in the customer's own name, kept in that currency.

Open one fiat-only EUR or GBP account with an IBAN in the customer's own name. The account keeps the money in that currency.

API version: v2.

Who it is for. A UK accounting app whose small-business customers want to receive pounds or euros into an account in their own name, kept in that currency.

Status. Available in the countries the option serves, in EUR or GBP, with one account per customer.

Money example

Northwind Design Ltd in Manchester invoices a Dutch client 4,800.00 EUR.

The client sends 4,800.00 EUR by SEPA to Northwind's IBAN.
The bank credits 4,800.00 EUR. Gravv books the deposit and sends transfer.inflow.completed.
Northwind can later pay out from the EUR balance.

Before you start

The customer's basic KYC is completed. For a business, every associated person's KYC is completed first.
Capabilities show a EUR or GBP option with token_wallets: [] and max_accounts_per_customer: 1. The bank issues one IBAN per customer, so choose EUR or GBP. The API refuses the second account.
Send this option's bank_code. Without it, EUR and GBP requests go to the wallet-backed default.

Find out what is required

Read requirements with currency set to EUR or GBP, plus this option's bank_code and country. EUR and GBP use the same form.

	A person	A business
Always	Names, `date_of_birth`, `birth_place`, `email`, `phone_daytime`, `citizenship_country`, `permanent_address` (`address_line`, `city`, `postal_code`, `country`)	`legal_name`, `registration_number`, `incorporation_country`, `incorporation_date`, `business_description`, `website`, `business_address`
When it applies	`tax_id_type` (`ssn` or `tin`) and `tax_id_number` when the person pays tax in the US	`business_tax_id` for a US company
Parties	None	1 to 10, each with names, `email` and `party_role`. A party with ownership also needs `date_of_birth` and `ownership_percentage`. At least one party has `has_ownership: true`
Documents	One identity document with `number`, `issuing_country` and `expiration_date`, and `proof_of_address`	`articles_of_incorporation` and `proof_of_address`, plus one identity document per party

The API refuses P.O. Box addresses. UK and Nigerian postal codes must be valid for their country.

Steps

1. Open the account, with no `network`

curl --request POST \
 --url https://api.gravv.xyz/v2/accounts \
 --header 'Api-Key: <API_KEY>' \
 --header 'Idempotency-Key: 904e87fa-e6f5-4936-93af-6868e31e6ffa' \
 --header 'Content-Type: application/json' \
 --data '
{
"customer_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
"customer_type": "business",
"currency": "EUR",
"account_type": "operating",
"category": "sub_account",
"bank_code": "<bank_code>",
"label": "Northwind EUR",
"data": {
"root": {
  "legal_name": "Northwind Design Ltd",
  "registration_number": "09876543",
  "incorporation_country": "GB",
  "incorporation_date": "2016-09-12",
  "business_description": "Brand and packaging design studio",
  "website": "https://northwind-design.example",
  "business_address": {"address_line": "20 Quay Street", "city": "Manchester", "postal_code": "M3 3HN", "country": "GB"}
},
"parties": [
  {
    "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
    "party_role": "primary",
    "has_ownership": true,
    "ownership_percentage": 100,
    "has_control": true,
    "is_signer": true,
    "is_director": true,
    "date_of_birth": "1987-05-09",
    "citizenship_country": "GB",
    "documents": [
      {"document_type": "passport", "issuing_country": "GB", "number": "530112874", "issued_date": "2020-03-01", "expiration_date": "2030-03-01", "filename": "passport.jpg", "content": "<base64>"}
    ]
  }
],
"documents": [
  {"document_type": "articles_of_incorporation", "issuing_country": "GB", "filename": "articles.pdf", "content": "<base64>"},
  {"document_type": "proof_of_address", "issuing_country": "GB", "filename": "company-bill.pdf", "content": "<base64>"}
]
}
}
'

const response = await fetch("https://api.gravv.xyz/v2/accounts", {
method: "POST",
headers: {
"Api-Key": process.env.GRAVV_API_KEY,
"Idempotency-Key": "904e87fa-e6f5-4936-93af-6868e31e6ffa",
"Content-Type": "application/json",
},
body: JSON.stringify({
"customer_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
"customer_type": "business",
"currency": "EUR",
"account_type": "operating",
"category": "sub_account",
"bank_code": "<bank_code>",
"label": "Northwind EUR",
"data": {
  "root": {
    "legal_name": "Northwind Design Ltd",
    "registration_number": "09876543",
    "incorporation_country": "GB",
    "incorporation_date": "2016-09-12",
    "business_description": "Brand and packaging design studio",
    "website": "https://northwind-design.example",
    "business_address": {
      "address_line": "20 Quay Street",
      "city": "Manchester",
      "postal_code": "M3 3HN",
      "country": "GB"
    }
  },
  "parties": [
    {
      "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
      "party_role": "primary",
      "has_ownership": true,
      "ownership_percentage": 100,
      "has_control": true,
      "is_signer": true,
      "is_director": true,
      "date_of_birth": "1987-05-09",
      "citizenship_country": "GB",
      "documents": [
        {
          "document_type": "passport",
          "issuing_country": "GB",
          "number": "530112874",
          "issued_date": "2020-03-01",
          "expiration_date": "2030-03-01",
          "filename": "passport.jpg",
          "content": "<base64>"
        }
      ]
    }
  ],
  "documents": [
    {
      "document_type": "articles_of_incorporation",
      "issuing_country": "GB",
      "filename": "articles.pdf",
      "content": "<base64>"
    },
    {
      "document_type": "proof_of_address",
      "issuing_country": "GB",
      "filename": "company-bill.pdf",
      "content": "<base64>"
    }
  ]
}
}),
});
console.log(response.status, await response.json());

import os

import requests

response = requests.post(
"https://api.gravv.xyz/v2/accounts",
headers={
    "Api-Key": os.environ["GRAVV_API_KEY"],
    "Idempotency-Key": "904e87fa-e6f5-4936-93af-6868e31e6ffa",
    "Content-Type": "application/json",
},
json={
    "customer_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
    "customer_type": "business",
    "currency": "EUR",
    "account_type": "operating",
    "category": "sub_account",
    "bank_code": "<bank_code>",
    "label": "Northwind EUR",
    "data": {
        "root": {
            "legal_name": "Northwind Design Ltd",
            "registration_number": "09876543",
            "incorporation_country": "GB",
            "incorporation_date": "2016-09-12",
            "business_description": "Brand and packaging design studio",
            "website": "https://northwind-design.example",
            "business_address": {
                "address_line": "20 Quay Street",
                "city": "Manchester",
                "postal_code": "M3 3HN",
                "country": "GB",
            },
        },
        "parties": [
            {
                "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
                "party_role": "primary",
                "has_ownership": True,
                "ownership_percentage": 100,
                "has_control": True,
                "is_signer": True,
                "is_director": True,
                "date_of_birth": "1987-05-09",
                "citizenship_country": "GB",
                "documents": [
                    {
                        "document_type": "passport",
                        "issuing_country": "GB",
                        "number": "530112874",
                        "issued_date": "2020-03-01",
                        "expiration_date": "2030-03-01",
                        "filename": "passport.jpg",
                        "content": "<base64>",
                    },
                ],
            },
        ],
        "documents": [
            {
                "document_type": "articles_of_incorporation",
                "issuing_country": "GB",
                "filename": "articles.pdf",
                "content": "<base64>",
            },
            {
                "document_type": "proof_of_address",
                "issuing_country": "GB",
                "filename": "company-bill.pdf",
                "content": "<base64>",
            },
        ],
    },
},
)
print(response.status_code, response.json())

The API returns {"account_id": "…", "status": "pending"}.

For a person's GBP account, change the request like this:

Send customer_type individual and currency GBP.
Send no parties.
Send the person's root fields, including birth_place.
Send an identity document and proof_of_address in data.documents.

2. Follow it until it is active

Read GET /v2/accounts/{id} until the status is active. The IBAN appears when the bank allocates it.

3. Give the details to the payer

virtual_account_bank_account_number holds the full IBAN, and virtual_account_bank_routing_number holds the sort code. The BIC is in virtual_account_bank_metadata. For a UK Faster Payment, the 8-digit account number is the last 8 digits of the GB IBAN. See Share account details and receive a deposit.

What can go wrong

Every error in the wallet-backed recipes that does not concern the network can happen here too. These errors are specific to this option:

Response	Why	Fix
409 `this customer already holds the maximum number of EUR/GBP accounts permitted for this account type (1)`	The customer already has this option's account, in either currency	Use that account. The bank issues one IBAN per customer
400 `network is only accepted for account options that support wallet integration`	You sent `network`	Remove it
400 `details.birth_place`: `required: is required`	A person has no place of birth	Ask for their town of birth
400 `details.permanent_address.postal_code`: `must be a valid UK postal code`	The UK postcode is malformed	Send a valid one, such as `EC1A 1BB`
400 `details.website`: `required: is required`	The business has no website	Send the company website
`status_reason` `manual_review_requested` soon after create, for a business	The bank refused the request. For example, no party has `has_ownership: true`, or an ID has no expiry date	Contact support with the account id. On a new attempt, declare an owner and full ID details