Approving payments - global-121/121-platform GitHub Wiki

Payment phases and "segregation of duties"

Progressing a payment happens through multiple actions:

  1. Create payment
  2. Approve payment (potentially multiple steps)
  3. Start payment

The permissions to take these actions can and should be split across different users, according to the principle of "segregation of duties".

How approval thresholds work

Approvals are configured using approval thresholds. Each threshold defines:

  • A thresholdAmount — the minimum payment amount at which this approval step becomes required.
  • One or more userIds — the users who can approve this step. Any one of the assigned users can approve; only one approval per step is needed.

When a payment is created, all thresholds whose thresholdAmount is less than or equal to the payment's transfer value apply. Each applicable threshold becomes one approval step, ordered from lowest to highest threshold amount (rank 1, rank 2, etc.). All steps must be approved in order before the payment can proceed.

Example

Threshold amount Approvers
0 Alice
100 Bob or Carol
  • A payment of €50: only the threshold 0 applies → 1 approval step (Alice).
  • A payment of €150: both thresholds apply → 2 steps (Alice first, then Bob or Carol).

The threshold with thresholdAmount: 0 covers all payments and is therefore required in every configuration.

Configuring approval thresholds

Approval thresholds are configured per program by an organization admin, using the API:

  • PUT /api/programs/{programId}/approval-thresholds — replaces the entire threshold configuration atomically.
  • GET /api/programs/{programId}/approval-thresholds — retrieves the current configuration.

The PUT endpoint accepts an array of threshold objects. Each object requires:

  • thresholdAmount (number, ≥ 0)
  • userIds (array of user IDs, at least one)

Validation rules

  • At least one threshold with thresholdAmount: 0 must be included (to cover all payments below the first non-zero threshold).
  • Threshold amounts must be unique across the configuration.
  • Each threshold must have at least one approver.
  • A user can only appear in one threshold — a user cannot be an approver for multiple thresholds in the same program.
  • Approvers must be assigned to the program without a scope; scoped users cannot be approvers.
  • All userIds must belong to users already assigned to the program.

Updating the configuration

Because the PUT endpoint replaces all thresholds at once, to add, remove, or change a threshold you submit the full new desired configuration. The existing configuration is deleted and replaced in a single transaction.

Note: Changes to thresholds only affect future payments. A payment already created retains the approval steps that were configured at the time of its creation.

When no thresholds are configured

If no approval thresholds are configured for a program, creating a payment will be blocked.

Seeding approver-mode & approver default-role

When seeding, there is an approverMode attribute with 3 values:

  • none — to be used on production instances. No thresholds are created; they must be configured manually via the API after seeding.

  • admin — used for local development and testing. Creates a single threshold with thresholdAmount: 0 assigned to the admin user.

  • demo — used for demos. Creates two thresholds:

    • thresholdAmount: 0 → admin user + approver user
    • thresholdAmount: 100 → finance manager user + CVA manager user

    Additionally, an [email protected] user is created and assigned the approver default role. This default role has only the basic permissions to view the portal and particularly the payment page, where the approve action happens.

    NOTE: having the approver role is something completely separate from being assigned as an approver in a threshold. The latter is what controls who can actually approve payments. Users of any role can be configured as an approver in a threshold. The default role exists as a convenience starting point for clients.