Existing User

Capture payer accounts with x-customer-id, list them, and reuse them on later payment requests.

The Existing User journey is for merchants that do not onboard bank accounts themselves, but want Spare to collect account details through Open Finance and return them for returning payers. After capture, you can show previously used accounts and attach one on a later create, which reduces bank-account selection friction.

This journey has two phases: capture, then reuse. Permissions requirements are covered in Consent Permissions.

When To Use

Use this journey when you want Spare to collect accounts through Open Finance and return them for returning payers.

Example use cases

Capture the payer account via bank APIs during consent, without onboarding IBANs yourself
Show previously used accounts to the same end user in your UI
Subsequent payments that use Debtor Account or savedDebtorAccountId so the hosted flow can skip account selection

Do not send a non-UUID x-customer-id. The header must be a valid UUID v4 that you stably associate with that end user in your system.

How It Works

Capture

You create a payment request with header x-customer-id set to your end-user UUID v4, and with the necessary consentPermissions so Spare can read account details.
The payer authorises at their bank.
Spare collects the account information and tags it to the same x-customer-id.

Reuse

You call GET /payment/saved-debtor-accounts with the same x-customer-id (and x-tenant: UAE).
You display the returned accounts (masked identification, holder name, provider) in your UI.
On a later POST /payment-requests, you either:
- set savedDebtorAccountId to the saved account id (requires x-customer-id), or
- set debtorAccount from the details you hold (see Debtor Account)
debtorAccount and savedDebtorAccountId are mutually exclusive.

Fields and Headers

Name	Where	Presence	Description
`x-customer-id`	Header	Required for capture tagging and for `savedDebtorAccountId` / list	Merchant-supplied end-user id. Must be a valid UUID v4.
`consentPermissions`	Body	Required for useful capture	Permission codes that allow Spare to read account details. See Consent Permissions.
`savedDebtorAccountId`	Body	Optional on later creates	Id of a previously saved debtor account. Requires `x-customer-id`. Mutually exclusive with `debtorAccount`.

List response (`GET /payment/saved-debtor-accounts`)

Field	Description
`id`	Saved debtor account id. Pass as `savedDebtorAccountId` on create.
`maskedIdentification`	Masked account identifier for display.
`accountHolderName`	Account holder name when available.
`scheme`	Account scheme (for example `IBAN`).
`provider`	Provider object (`id`, `code`, `name`, `logoUrl`) when available.
`status`	Status of the saved account.
`createdAt`	When Spare stored the account.

Example: Capture create

{
  "type": "SingleInstantPayment",
  "creditorType": "MERCHANT",
  "creditorReference": "INV10042",
  "merchantReference": "uj-existing-capture-10042",
  "purpose": "GDDS",
  "consentPermissions": [
    "ReadAccountsBasic",
    "ReadAccountsDetail"
  ],
  "creditorAccount": {
    "schemeName": "IBAN",
    "identification": "AE070331234567890123456",
    "name": "Acme Trading LLC"
  },
  "successRedirectUrl": "https://merchant.example/payments/success",
  "failureRedirectUrl": "https://merchant.example/payments/failure",
  "instructions": {
    "amount": { "amount": "125.50", "currency": "AED" }
  }
}

Send that body with headers Authorization: Bearer <token>, x-tenant: UAE, and x-customer-id: f47ac10b-58cc-4372-a567-0e02b2c3d479.

Example: Reuse with `savedDebtorAccountId`

{
  "type": "SingleInstantPayment",
  "creditorType": "MERCHANT",
  "creditorReference": "INV10043",
  "merchantReference": "uj-existing-reuse-10043",
  "purpose": "GDDS",
  "savedDebtorAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "creditorAccount": {
    "schemeName": "IBAN",
    "identification": "AE070331234567890123456",
    "name": "Acme Trading LLC"
  },
  "successRedirectUrl": "https://merchant.example/payments/success",
  "failureRedirectUrl": "https://merchant.example/payments/failure",
  "instructions": {
    "amount": { "amount": "80.00", "currency": "AED" }
  }
}

Send with the same x-customer-id used at capture.

What Fails

Spare rejects the create when:

x-customer-id is present but not a valid UUID
savedDebtorAccountId is set without x-customer-id
savedDebtorAccountId and debtorAccount are both set
savedDebtorAccountId does not belong to that x-customer-id

List calls without x-customer-id fail validation (x-customer-id is required on GET /payment/saved-debtor-accounts).

See Error codes for response shapes.

Reuse via Debtor Account

If you prefer to send the full IBAN yourself after the user picks a saved account in your UI, use the Debtor Account journey instead of savedDebtorAccountId.

Continue learning

User Journeys

Journey picker and combining rules.

Consent Permissions

Permission codes required for account capture.

Debtor Account

Reuse by supplying debtorAccount on create.

Payment Requests

Create endpoint and related payment operations.

On this page