Setup your Bank Account

Integration guide

Goal: Register the bank account that receives settled payments and mark it as default.

Estimated time: 10 minutes

Prerequisites

Sandbox credentials
For sandbox: use the dummy IBAN / BICFI values below (production uses your real account identifiers)

A creditor bank account is the settlement account that receives funds after a payment settles. You register at least one account and mark one as default before you create payment requests that settle to your business.

What You Need

Sandbox credentials from Quick Start Setup.

Sandbox accepts only dummy account identifiers:

Field	Scheme	Identification
Account details	`IBAN`	`10000109010101`
Bank details	`BICFI`	`10000109010101`

Production registrations use your real IBAN and bank identifiers.

Onboarding Methods

You can register a creditor bank account in one of three ways. Choose one path; you do not need to complete all three.

Method	When to use it
Spare portal	Manual setup in the dashboard, with no code
REST API	Server-side registration with direct HTTP calls
Official SDK	Typed client calls from your backend

After you register an account, set it as default so settlements route to it.

The React Native and Flutter SDKs drive the payer payment UI. They do not register creditor bank accounts.

SDK availability

The TypeScript snippets use the published @spare-technologies/spare-api package (v1.0.0, UAE). The Python, Java, C#, and Go SDKs are still under review; for those languages, register over the REST (cURL) tab or the Bank accounts API until they ship.

Register via the Spare Portal

Use the portal when you want to add a settlement account without writing API calls.

Sign in to the sandbox dashboard.
Open Payment Initiation → Settings.
On the Bank account page, click Add New Bank account.
Enter account holder details, account type, and bank details. Address is optional.
Save the account and note its account id.

Then set that account as default over REST or an SDK.

Register over REST or an SDK

Use this path when your backend registers creditor accounts. The cURL tab is the REST API. The language tabs are the official SDKs.

List Existing Accounts (Optional)

Call list first when you want to avoid creating a duplicate account.

curl https://api.sandbox.tryspare.ae/payment/bank-account \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-tenant: UAE"

const existing = await client.bankAccounts.list();

existing = client.bank_accounts.list()

var existing = client.bankAccounts().list(ListBankAccounts.builder().build());

var existing = await client.BankAccounts.ListAsync(new ListBankAccounts());

existing, err := client.BankAccounts.List(ctx, &spareapi.ListBankAccounts{})
if err != nil {
    log.Fatal(err)
}

Register a New Account

POST /payment/bank-account creates the creditor account. The response returns the account under data, including its id.

curl -X POST https://api.sandbox.tryspare.ae/payment/bank-account \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-tenant: UAE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Settlement Account",
    "type": "Business",
    "accountDetails": {
      "scheme": "IBAN",
      "identificationNumber": "10000109010101"
    },
    "accountHolderDetails": {
      "name": "Acme Trading LLC"
    },
    "bankDetails": {
      "name": "Example Bank",
      "scheme": "BICFI",
      "identificationNumber": "10000109010101"
    }
  }'

const account = await client.bankAccounts.create({
  iban: "10000109010101",
  accountHolderName: "Acme Trading LLC",
  bankName: "Example Bank",
});

account = client.bank_accounts.create(
    iban="10000109010101",
    account_holder_name="Acme Trading LLC",
    bank_name="Example Bank",
)

var account = client.bankAccounts().create(CreateBankAccount.builder()
    .iban("10000109010101")
    .accountHolderName("Acme Trading LLC")
    .bankName("Example Bank")
    .build());

var account = await client.BankAccounts.CreateAsync(new CreateBankAccount
{
    Iban              = "10000109010101",
    AccountHolderName = "Acme Trading LLC",
    BankName          = "Example Bank",
});

account, err := client.BankAccounts.Create(ctx, &spareapi.CreateBankAccount{
    Iban:              "10000109010101",
    AccountHolderName: "Acme Trading LLC",
    BankName:          "Example Bank",
})
if err != nil {
    log.Fatal(err)
}

Set as Default

Only one creditor account is the default. After you register an account (portal or API), set that account as default so settlements route to it.

Replace BANK_ACCOUNT_ID with the id returned at create time, or the id shown for the account in the portal.

curl -X PUT "https://api.sandbox.tryspare.ae/payment/bank-account/default?id=BANK_ACCOUNT_ID&isDefault=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-tenant: UAE"

await client.bankAccounts.setDefault({
  bankAccountId: account.data.id,
});

client.bank_accounts.set_default(bank_account_id=account.data.id)

client.bankAccounts().setDefault(SetDefaultBankAccount.builder()
    .bankAccountId(account.getData().getId())
    .build());

await client.BankAccounts.SetDefaultAsync(new SetDefaultBankAccount
{
    BankAccountId = account.Data.Id,
});

_, err = client.BankAccounts.SetDefault(ctx, &spareapi.SetDefaultBankAccount{
    BankAccountId: account.Data.Id,
})
if err != nil {
    log.Fatal(err)
}

Verify Default

Confirm the default account before you create payment requests.

curl https://api.sandbox.tryspare.ae/payment/bank-account/default \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-tenant: UAE"

const defaultAccount = await client.bankAccounts.getDefault();

default_account = client.bank_accounts.get_default()

var defaultAccount = client.bankAccounts().getDefault(GetDefaultBankAccount.builder().build());

var defaultAccount = await client.BankAccounts.GetDefaultAsync(new GetDefaultBankAccount());

defaultAccount, err := client.BankAccounts.GetDefault(ctx, &spareapi.GetDefaultBankAccount{})
if err != nil {
    log.Fatal(err)
}

What Can Go Wrong

Symptom	Likely cause	What to do
`400` on create in sandbox	IBAN or BICFI is not the dummy value	Use `10000109010101` for both identifiers in sandbox
`401` / `403`	Missing or invalid bearer token, or wrong tenant	Re-authenticate and send `Authorization: Bearer` with `x-tenant: UAE`
Create succeeds but payments fail to settle to you	No default account, or the wrong account is default	Call set default, then get default to confirm

Full schemas and error shapes: Bank accounts API.

Key takeaways

Choose one onboarding path: Spare portal, REST, or an official SDK. You do not need all three.
Register creditor accounts before you create payment requests that settle to your business.
Sandbox accepts only the dummy IBAN and BICFI identifiers shown above; production uses your real account details.
Only one account is default; update with set default when your banking details change or when you add multiple accounts.

Continue learning

Payments

Full payment flow after bank account setup.

Environments

Sandbox vs production configuration.

On this page