Variable On Demand with Multiple Beneficiaries

The Variable On Demand with Multiple Beneficiaries journey lets you collect to more than one creditor account under a single VariableOnDemand consent. The payer authorizes once. You then pick which authorized account receives each debit when you schedule it.

Shared VariableOnDemand instructions live on Variable On Demand. This page covers the extra creditors on create and the creditorAccountId field on POST /mandate/schedule.

When To Use

Use this journey when one payer should fund several of your beneficiary accounts without a new consent for each payee.

Do not set additionalCreditorAccounts on any type other than VariableOnDemand. For a single creditor, omit the field. You still send creditorAccountId when you schedule a Variable On Demand debit.

How It Works

1. You create a VariableOnDemand payment request. Set creditorAccount as the default payee. Add extra payees in additionalCreditorAccounts.
2. Spare stores the authorized creditor set. The create response returns an id on creditorAccount and on each additional account.
3. You send the payer into the hosted flow. The payer authorizes one consent that covers that set.
4. For each debit, you call POST /mandate/schedule with creditorAccountId set to the account that should receive that payment.

You can combine this journey with Debtor Account, Pre-selected Provider, or Consent Permissions. Those controls do not replace the creditor set.

Additional Creditor Accounts

On POST /payment-requests, creditorAccount remains required. additionalCreditorAccounts is an optional array of extra payees.

Primary plus additional accounts must total at most 10. Each account must be unique by scheme and identification. Create-time validation for this field is on Variable On Demand.

Store every returned id. You pass one of those ids as creditorAccountId on schedule. You can also re-read them from GET /payment-requests/{paymentRequestId}.

Example: Create with Extra Creditors

Focused create body for VariableOnDemand with one additional creditor. Keep instructions within the Variable On Demand control set.

{
  "type": "VariableOnDemand",
  "creditorType": "MERCHANT",
  "creditorReference": "MKTPLACE01",
  "merchantReference": "vod-multi-01",
  "purpose": "GDDS",
  "creditorAccount": {
    "schemeName": "IBAN",
    "identification": "AE070331234567890123456",
    "name": "Acme Marketplace LLC"
  },
  "additionalCreditorAccounts": [
    {
      "schemeName": "IBAN",
      "identification": "AE070331234567890123457",
      "name": "Acme Seller Settlements LLC"
    }
  ],
  "successRedirectUrl": "https://merchant.example/payments/success",
  "failureRedirectUrl": "https://merchant.example/payments/failure",
  "instructions": {
    "maxCumulativeNumberOfPayments": 20,
    "maxCumulativeAmount": { "amount": "200.00", "currency": "AED" },
    "periodicSchedule": {
      "frequency": "Week",
      "startDate": "2026-08-12",
      "endDate": "2027-08-01",
      "maxAmount": { "amount": "50.00", "currency": "AED" },
      "controls": {
        "maxCumulativeAmountPerPeriod": { "amount": "100.00", "currency": "AED" }
      }
    }
  }
}

The create response includes creditorAccount.id and additionalCreditorAccounts[].id. Use those values on schedule.

Mandate Schedule

For VariableOnDemand, creditorAccountId is required on POST /mandate/schedule. Spare uses it to select which authorized creditor receives that debit.

This requirement applies to every Variable On Demand schedule, including when you omitted additionalCreditorAccounts. In that case pass creditorAccount.id from the payment request.

creditorAccountId is not accepted on other payment types. Spare rejects the schedule if you send it on FixedOnDemand or a periodic or defined-schedule mandate.

Do not send creditorAccountId on PATCH /mandate/approve. Creditor selection is set at schedule and does not change on approve.

Signing and the rest of the schedule contract are in Manage Your Mandates.

Example: Schedule to a Selected Creditor

Schedule a Variable On Demand debit to the additional creditor. Replace the ids with values from your create or get response.

{
  "mandateId": "7f2a8c1b-4e09-4d6a-9c12-8b3f5e6d7a01",
  "executionDate": "2026-08-20T00:00:00Z",
  "amount": { "amount": "35.00", "currency": "AED" },
  "creditorAccountId": "858704f9-db10-40ff-a79d-12e658ec2713"
}

The schedule response returns data.id as the new transaction identifier. The transaction includes creditorAccount for the selected payee.

What Fails

Spare rejects the create when additionalCreditorAccounts is invalid for the type, exceeds 10 accounts including the primary, or duplicates another creditor by scheme and identification. See Variable On Demand.

Spare rejects POST /mandate/schedule when:

• the mandate is VariableOnDemand and creditorAccountId is missing
• creditorAccountId is not a valid UUID
• creditorAccountId is not in the authorized creditor set for that payment request
• creditorAccountId is set on a payment type other than VariableOnDemand

See Error codes for response shapes.