Payment Request Deep Dives
Field-level controls for each payment type on POST /payment-requests.
Spare exposes one create endpoint for every payment type. You set type on POST /payment-requests. Type-specific fields live in instructions.
Why One Endpoint
Spare handles every payment type behind one create endpoint so you can support the Open Finance payment types your product needs without integrating each type separately. You integrate and test against POST /payment-requests, then choose the type with type and the matching instructions fields.
Rules and updates for individual payment types land on that same endpoint. You do not maintain a different create path per type when a type's fields or validation change.
When Spare ships new payer journeys that use these payment types, you can adopt them with minimal changes on your side: same endpoint, updated type and instructions where your use case requires it.
Create requests require request signing. See Request Signing.
Choose a Payment Type
Payment types group by how amounts and schedules work:
| Group | What it is | Types |
|---|---|---|
| On-Demand | You initiate payments at any time, with no fixed payment dates. Limits reset on a rolling period you define. | FixedOnDemand, VariableOnDemand |
| Periodic (recurring) | Payments run on a regular schedule: daily, weekly, monthly, or yearly. | FixedPeriodicSchedule, VariablePeriodicSchedule |
| Defined | Payments are pre-scheduled for specific calendar dates. | FixedDefinedSchedule, VariableDefinedSchedule |
| Single instant | One fixed amount, one immediate debit. | SingleInstantPayment |
| Type | Amount model | Schedule model | Guide |
|---|---|---|---|
SingleInstantPayment | Fixed amount | Immediate | Single Instant Payment |
FixedPeriodicSchedule | Fixed amount | Regular recurring schedule | Fixed Periodic Schedule |
VariablePeriodicSchedule | Up to a max amount | Regular recurring schedule | Variable Periodic Schedule |
FixedOnDemand | Fixed amount | You trigger each debit | Fixed On Demand |
VariableOnDemand | Up to a max amount | You trigger each debit | Variable On Demand |
FixedDefinedSchedule | Fixed amount per date | Explicit date list | Fixed Defined Schedule |
VariableDefinedSchedule | Max amount per date | Explicit date list | Variable Defined Schedule |
Shared Request Fields
These root fields apply on create. Most apply to every payment type. Fields marked Conditional* apply only under the condition in Description. Fields marked Optional* are work in progress. Type pages document instructions in detail.
Root body
| Field | Presence | Description |
|---|---|---|
type | Required | Payment type enum. Selects the instructions validation rules. |
creditorType | Required | Creditor kind: MERCHANT, USER, or CREDITOR. |
creditorAccount | Required | Payee account that receives funds. Nested fields below. |
additionalCreditorAccounts | Conditional* | Extra creditor accounts beyond creditorAccount. Valid only when type is VariableOnDemand. Primary plus additional accounts must total at most 10, and each account must be unique by scheme and identification. See Variable On Demand. |
purpose | Required | Payment purpose code. See Payment purpose codes. |
merchantReference | Required | Your idempotent merchant reference for this request. |
instructions | Required | Type-specific fields. Shape depends on type. See Instructions Building Blocks. |
creditorReference | Optional | Your reference for the creditor. Max 22 characters. No hyphens. |
debtorReference | Optional | Your reference for the payer. |
debtorAccount | Optional | Payer account when you already know it. When omitted, the bank prompts the payer to choose. Mutually exclusive with savedDebtorAccountId. Nested fields below. |
savedDebtorAccountId | Optional | Previously saved debtor account id. Requires x-customer-id. Mutually exclusive with debtorAccount. |
successRedirectUrl | Optional | Browser return URL after successful authorization. |
failureRedirectUrl | Optional | Browser return URL after failed or cancelled authorization. |
channel | Optional | Where the hosted flow opens (browser vs app deep-link). Controls how Spare returns the payer after bank authorization. |
consentPermissions | Optional | Extra consent permission strings when your product needs them. |
risks* | Optional* | Work in progress. Optional risk indicators for the payment context. The final object and field structure will change; do not hard-depend on the current shape. |
creditorAccount
| Field | Presence | Description |
|---|---|---|
schemeName | Required | Account scheme. Spare accepts IBAN for UAE create. |
identification | Required | Account identifier for the scheme (IBAN value). |
name | Optional | Creditor account holder name. |
debtorAccount
| Field | Presence | Description |
|---|---|---|
schemeName | Required | Account scheme (IBAN). |
identification | Required | Payer IBAN. |
name | Required | Payer name. Required when debtorAccount is supplied. |
Instructions Building Blocks
These objects appear across types. Each type page states which blocks apply and which fields are required.
| Block | What it is |
|---|---|
amount / maxAmount | Nested amount object: { "amount": "250.00", "currency": "AED" }. amount is a decimal string with two fraction digits. currency is ISO-4217 uppercase. Fixed types use amount. Variable types use maxAmount as the ceiling per debit or entry. |
maxCumulativeAmount | Optional lifetime ceiling: the maximum cumulative value of payments that may be initiated over the lifetime of the consent. When you set it, its value must be greater than the individual debit amount (amount or maxAmount), except where a type page requires an exact total (periodic amount × payment count, or the sum of a defined schedule). |
maxCumulativeNumberOfPayments | Optional lifetime ceiling: the maximum cumulative number of payments that may be initiated over the lifetime of the consent. Must be greater than zero when set. Type pages state how you must calculate it. |
periodicSchedule | Schedule object for periodic and on-demand types: frequency, startDate, endDate, and amount fields. On on-demand types it also carries controls. |
controls | On-demand types only (FixedOnDemand, VariableOnDemand). Nested under periodicSchedule. Defines rolling per-period limits that reset each frequency window (Day, Week, Month, or Year). See the on-demand pages. |
paymentSchedule | Array of dated entries for defined-schedule types. Each entry has paymentExecutionDate plus amount or maxAmount. |
isInternationalPayment / currencyRequest | Cross-border flags and FX/transfer metadata. Supported on Single Instant and defined-schedule types under the rules on those pages. Rejected on periodic and on-demand types. |
permissions | Optional consent-scope booleans (readAccountsBasic, readAccountsDetail, readBalances, readRefundAccount, confirmPayee). When confirmPayee is omitted, Spare defaults it to true. |
copCreditorName | Optional creditor name parts used when Confirmation of Payee needs structured names. |
Lifetime vs rolling limits
- Lifetime fields (
maxCumulativeAmount,maxCumulativeNumberOfPayments) bound the whole consent. - Rolling fields live in
periodicSchedule.controlsand apply only to on-demand types. They bound activity inside onefrequencyperiod, then reset for the next period.
Example: on VariableOnDemand, frequency is Week and controls.maxCumulativeAmountPerPeriod is AED 100. You may initiate up to AED 100 of debits in that week. Further debits in the same week are rejected. The AED 100 limit resets at the start of the next week.
Where Next
Single Instant Payment
One amount, one immediate debit.
Fixed Periodic Schedule
Fixed amount on a regular recurring schedule.
Variable Periodic Schedule
Variable amount up to a max on a regular schedule.
Fixed On Demand
Fixed amount; you trigger each debit.
Variable On Demand
Variable amount; you trigger each debit.
Fixed Defined Schedule
Fixed amounts on explicit dates.
Variable Defined Schedule
Max amounts on explicit dates.