Debtor Account

Pre-supply the payer IBAN on create so the hosted flow skips bank-account selection.

The Debtor Account journey lets you pass the payer's account in debtorAccount on POST /payment-requests. When Spare already has a valid debtor IBAN, the hosted flow skips the bank-account page and opens on the summary screen.

Shared root fields live on Payment Request Deep Dives. This page covers the debtor-account journey only.

When To Use

Use this journey when you already hold the user's bank account details on your platform and want fewer hosted steps.

Example use cases

Merchants that onboard bank accounts during signup or KYC
Checkout where the payer previously saved an IBAN with you
Returning-payer flows after you collected an account via the Existing User journey

Do not use this journey when you do not know a live UAE Open Finance IBAN for the payer. In that case omit debtorAccount and let the bank prompt the payer, or use Pre-selected Provider if you only know the bank.

How It Works

You create a payment request with debtorAccount set (schemeName, identification, name).
Spare validates the account shape. The IBAN must belong to a bank that is live on the UAE Open Finance network.
You send the payer into the hosted flow. Spare skips the bank-account selection page.
The payer reviews the summary screen, then continues to their bank to authorise.

debtorAccount is mutually exclusive with savedDebtorAccountId. To reuse an account Spare previously saved for a customer id, see Existing User.

Fields

Field	Presence	Description
`debtorAccount`	Optional	Payer account when you already know it. Mutually exclusive with `savedDebtorAccountId`.
`debtorAccount.schemeName`	Required when object set	Account scheme. Use `IBAN` for UAE create.
`debtorAccount.identification`	Required when object set	Payer IBAN. Must belong to a live UAE Open Finance bank.
`debtorAccount.name`	Required when object set	Payer account holder name.

Example

Focused create body for a domestic SingleInstantPayment with a pre-supplied debtor account. Adjust type and instructions for other payment types using Payment Request Deep Dives.

{
  "type": "SingleInstantPayment",
  "creditorType": "MERCHANT",
  "creditorReference": "INV10042",
  "merchantReference": "uj-debtor-10042",
  "purpose": "GDDS",
  "creditorAccount": {
    "schemeName": "IBAN",
    "identification": "AE070331234567890123456",
    "name": "Acme Trading LLC"
  },
  "debtorAccount": {
    "schemeName": "IBAN",
    "identification": "AE460090000000123456789",
    "name": "Fatima Al Hashimi"
  },
  "successRedirectUrl": "https://merchant.example/payments/success",
  "failureRedirectUrl": "https://merchant.example/payments/failure",
  "instructions": {
    "amount": { "amount": "125.50", "currency": "AED" }
  }
}

What Fails

Spare rejects the create when:

debtorAccount is present but name, schemeName, or identification is missing
debtorAccount and savedDebtorAccountId are both set
the debtor IBAN is not usable on the UAE Open Finance network (not a live registered bank)

You can combine debtorAccount with providerId. See Combining Journeys.

See Error codes for response shapes.

Continue learning

User Journeys

Journey picker and combining rules.

Existing User

Capture and reuse saved debtor accounts.

Payment Request Deep Dives

Shared root fields including debtorAccount.

Payment Requests

API reference for create, get, list, and delete.

When To Use

How It Works

Fields

Example

What Fails

On this page