User Journeys
Optional create-time controls that change the hosted payer flow, consent data, or Variable On Demand creditors.
User journeys are optional controls on POST /payment-requests (and related headers or list endpoints) that change which hosted pages the payer sees, what account data Spare can read and share after consent, or which creditor accounts a Variable On Demand mandate can pay. Use them when you already know the bank or account, need account details for reconciliation, want to recognise returning payers, or need several payees under one consent.
Payment type fields live in instructions. See Payment Request Deep Dives for shared root fields and per-type rules.
Choose a Journey
| Journey | What it changes | Guide |
|---|---|---|
| Debtor Account | Supply debtorAccount so the hosted flow skips bank-account selection and opens on the summary screen. | Debtor Account |
| Pre-selected Provider | Supply providerId from GET /providers so the hosted flow skips bank selection and opens on the summary screen. | Pre-selected Provider |
| Consent Permissions | Add consentPermissions so Spare can read account details and/or balances and share them with you when the product needs them. | Consent Permissions |
| Existing User | Send x-customer-id with consent permissions so Spare can collect and tag account data, then list it for returning payers. | Existing User |
| Variable On Demand with Multiple Beneficiaries | Add additionalCreditorAccounts on VariableOnDemand so one consent can pay several creditors. Each POST /mandate/schedule must send creditorAccountId. | Variable On Demand with Multiple Beneficiaries |
Combining Journeys
| Combination | Hosted / data effect |
|---|---|
providerId only | Skip bank selection. Payer lands on the summary screen. |
debtorAccount only | Skip bank-account selection. Payer lands on the summary screen. The IBAN must belong to a live UAE Open Finance bank. |
providerId + debtorAccount | Skip both selection steps where applicable. Payer lands on the summary screen. |
savedDebtorAccountId with x-customer-id | Reuse a previously saved debtor account. Mutually exclusive with debtorAccount. |
consentPermissions only | Does not skip hosted pages. Widens consent scope. Spare discloses the permissions to the payer. |
Capture: x-customer-id + consent permissions | After successful bank authorisation, Spare tags collected account data to that customer id for later list and reuse. |
debtorAccount + savedDebtorAccountId | Invalid. Spare rejects the create. |
additionalCreditorAccounts on VariableOnDemand | Does not skip hosted pages. Widens the authorized creditor set. Each schedule must send creditorAccountId. |
Shared root fields and payment-type instructions are documented in Payment Request Deep Dives.
Where Next
Debtor Account
Pre-supply the payer IBAN and skip account selection.
Pre-selected Provider
Pre-supply the bank and skip bank selection.
Consent Permissions
Request account and balance data with the payment consent.
Existing User
Capture, list, and reuse saved debtor accounts.
Variable On Demand with Multiple Beneficiaries
One consent, several creditor accounts, selected at schedule.