Consent Permissions

Request account and balance data on the payment consent with consentPermissions.

In UAE Open Finance, a payer can complete a payment without sharing their bank account details with you or with Spare beyond what payment initiation needs. When your product needs the account used for the payment (reconciliation, refunds) or needs balance checks on long-duration consents, add consentPermissions on POST /payment-requests.

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

When To Use

Use this journey when your product needs account data beyond payment initiation.

Example use cases

Reconciliation or refunds where you need the account that funded the payment
Multi-payment (long-duration) consents where Spare reads the payer balance and rejects a debit before posting it to the bank when funds are insufficient, which avoids late failures

Do not add permissions you do not need. Extra permissions widen what Spare may read and what Spare discloses to the payer.

How It Works

You create a payment request with consentPermissions set to the permission codes your product needs.
Spare includes those permissions in the consent. On the hosted flow, Spare tells the payer how the permissions will be used.
You should also show clear messaging in your own UI whenever you add these permissions, so the payer understands the relationship before they authorise.
After successful authorisation, Spare can read the permitted account data and share it with you according to the consent.

For returning-payer capture that stores accounts against a customer id, combine this journey with Existing User.

Two permission surfaces

Root consentPermissions is a string array of permission codes on the create body. Payment Request Deep Dives also documents instructions.permissions as typed booleans (readAccountsBasic, readAccountsDetail, readBalances, readRefundAccount, confirmPayee). Use the surface your integration already sends; do not invent codes outside the table below for consentPermissions.

Fields

Field	Presence	Description
`consentPermissions`	Optional	Array of consent permission codes. Allowed values below.

Allowed `consentPermissions` codes

Code	What it allows
`ReadAccountsBasic`	Read basic account identifiers.
`ReadAccountsDetail`	Read detailed account information.
`ReadBalances`	Read account balances. Requires `ReadAccountsBasic` in the same array.
`ReadRefundAccount`	Read refund account details.

Example

Focused create body that requests account and balance permissions for reconciliation. For multi-payment types, keep the same consentPermissions pattern and set type / instructions from Payment Request Deep Dives.

{
  "type": "SingleInstantPayment",
  "creditorType": "MERCHANT",
  "creditorReference": "INV10042",
  "merchantReference": "uj-perms-10042",
  "purpose": "GDDS",
  "consentPermissions": [
    "ReadAccountsBasic",
    "ReadAccountsDetail",
    "ReadBalances"
  ],
  "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 consent step when:

a permission code is empty or not in the allowed set
ReadBalances is present without ReadAccountsBasic

Consent permissions alone do not skip hosted bank or account selection pages. See Combining Journeys.

See Error codes for response shapes.

Continue learning

User Journeys

Journey picker and combining rules.

Existing User

Capture saved accounts with x-customer-id and permissions.

Payment Request Deep Dives

Shared root fields and instructions.permissions.

Payment Requests

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