Defined Schedule Payments

Integration guide

Goal: Collect on explicit future dates with known amounts (loan-style repayment plans), using the FixedDefinedSchedule and VariableDefinedSchedule types.

Estimated time: 20 minutes

Prerequisites

Sandbox credentials (appId, apiKey, tenant)
A registered creditor bank account
Your full payment schedule (dates + amounts) known upfront

Mandate scheduling Payment flow

When to use

Loan repayment schedules with fixed dates
Installment plans where each installment date is known upfront
Corporate payment runs with a predefined calendar

Payment types: FixedDefinedSchedule, VariableDefinedSchedule
Regions: UAE (primary). Validate Bahrain/KSA support with Spare before launch.

How it differs from periodic

	Periodic schedule	Defined schedule
Dates	Rule-based (e.g. monthly)	Explicit list in `paymentSchedule[]`
Amount	Fixed or variable per period	Per-entry amount in schedule
Use case	Subscriptions	Amortization / installment tables

Integration summary

Build paymentSchedule array

Each entry includes date and amount (and currency). Variable schedules allow different amounts per slot.

curl -X POST https://api.sandbox.tryspare.ae/payment-requests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-tenant: UAE" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "FixedDefinedSchedule",
    "creditorType": "MERCHANT",
    "creditorReference": "Loan #4471",
    "merchantReference": "loan-4471",
    "purpose": "GDDS",
    "creditorAccount": {
      "schemeName": "IBAN",
      "identification": "AE070331234567890123456",
      "name": "Acme Trading LLC"
    },
    "instructions": {
      "paymentSchedule": [
        {
          "paymentExecutionDate": "2026-07-01",
          "amount": { "amount": "500.00", "currency": "AED" }
        },
        {
          "paymentExecutionDate": "2026-08-01",
          "amount": { "amount": "500.00", "currency": "AED" }
        }
      ]
    }
  }'

instructions: {
  paymentSchedule: [
    { date: "2026-07-01", amount: 500_00, currency: "AED" },
    { date: "2026-08-01", amount: 500_00, currency: "AED" },
  ],
}

instructions={
    "payment_schedule": [
        {"date": "2026-07-01", "amount": 500_00, "currency": "AED"},
        {"date": "2026-08-01", "amount": 500_00, "currency": "AED"},
    ]
}

Instructions.builder()
    .paymentSchedule(List.of(
        PaymentScheduleEntry.builder().date("2026-07-01").amount(500_00).currency("AED").build(),
        PaymentScheduleEntry.builder().date("2026-08-01").amount(500_00).currency("AED").build()
    ))
    .build();

new Instructions
{
    PaymentSchedule = new[]
    {
        new PaymentScheduleEntry { Date = "2026-07-01", Amount = 500_00, Currency = "AED" },
        new PaymentScheduleEntry { Date = "2026-08-01", Amount = 500_00, Currency = "AED" },
    }
};

&spareapi.Instructions{
    PaymentSchedule: []spareapi.PaymentScheduleEntry{
        {Date: "2026-07-01", Amount: 500_00, Currency: "AED"},
        {Date: "2026-08-01", Amount: 500_00, Currency: "AED"},
    },
}

Create payment request

Set paymentType to FixedDefinedSchedule or VariableDefinedSchedule and attach instructions.

Payer reviews the full schedule at their bank. One consent authorizes all listed debits (subject to mandate rules).

Execution

Spare executes each schedule entry on its date. Monitor via mandate transactions and webhooks.

Continue learning

Mandate Scheduling

Operational guide for mandates.

Mandates concept

Status machine and payment types.