Pre-selected Provider

Pre-supply providerId from GET /providers so the hosted flow skips bank selection.

The Pre-selected Provider journey lets you set providerId on POST /payment-requests after the payer chooses a bank in your UI. Spare skips the hosted bank-selection page and opens on the summary screen.

Shared root fields live on Payment Request Deep Dives. This page covers provider pre-selection only.

When To Use

Use this journey when you show the live bank list yourself and want one fewer click in the hosted flow.

Example use cases

Checkout that embeds your own bank picker
Flows where the payer's bank is already known from a previous step in your app

List live banks with GET /providers (countryCode=AE for UAE). Pass the chosen provider's id as providerId.

If you also know the payer IBAN, combine with Debtor Account. See Combining Journeys.

How It Works

Your backend calls GET /providers and returns the live list to your client.
The payer selects a bank in your UI.
You create a payment request with providerId set to that bank's UUID.
You send the payer into the hosted flow. Spare skips bank selection.
The payer reviews the summary screen, then continues to their bank to authorise.

Fields

Field	Presence	Description
`providerId`	Optional	UUID of a live provider from `GET /providers`. When set, Spare bypasses hosted bank selection.

Example

Focused create body with a pre-selected provider. Replace providerId with a live id from your sandbox or production provider list.

{
  "type": "SingleInstantPayment",
  "creditorType": "MERCHANT",
  "creditorReference": "INV10042",
  "merchantReference": "uj-provider-10042",
  "purpose": "GDDS",
  "providerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "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" }
  }
}

What Fails

Spare rejects the create or the hosted handoff when:

providerId is not a valid UUID
providerId does not match a live provider available to your tenant

See Error codes for response shapes.

Continue learning

User Journeys

Journey picker and combining rules.

Providers

List live banks and institutions.

Debtor Account

Also skip account selection when you know the IBAN.

Payment Requests

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

When To Use

How It Works

Fields

Example

What Fails

On this page