Approving payments

Approving payments

Payment phases and "segregation of duties"

Progressing a payment happens through multiple actions:

1. Create payment
2. Approve payment (potentially multiple)
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".

• This is not technically enforced however. Configuration can be such that one user can do all actions.
• In fact, upon initial deploy of this feature, all existing users with the payment.start permission (for a program) have been automatically configured as approver for that program (through data migration). This enabled a soft-launch, where initially anyone that could start a payment, can (and has to) approve the payment.
• It is expected however, that configuration will be changed to split these responsibilities.

Configuring approvers

• Approvers are configured separate from the normal permission-system of 121.
  • This means that 'approving a payment' is not an action that is protected by a specific 'approve-payment' permission, which is associated with a role that a user can have, like with normal permissions.
  • The reason for this is that the system needs to keep track of potentially multiple approvers and their approval status.
• When seeding a new production instance, the approverMode attribute should be set to 'none'. (Otherwise the admin-user becomes an approver for every payment.)
• The actual approvers must be set up per program via Swagger/API, using the api/programs/{programId}/approvers POST (to create), PATCH (to edit), DELETE (to delete) and GET (to check) endpoints. (In the future this may be possible via portal interface.)
• For creating a new approver for a given programId, the userId is needed, for example retrievable via GET api/users
• For editing or deleting an approver, the approverId is needed, retrievable via GET api/programs/{programId}/approvers
• The order attribute of approvers for a program determines the order in which approvers need to approve.
  • If an approver approvers too early, this will be blocked.
  • order must be unique per program, but can be any absolute value. The system will transform order values 1,5,8 to rank 1,2,3 automatically.
  • If you have order values 1,2,3, but want to switch 2 and 3 around, you can most easily do so by PATCH-ing 2 to 4.

Notes

• When no approvers are configured for a program, creating a payment will be blocked.
• When an approver is created or updated (order) after a payment is created, this will not affect the created payment. The new/changed approvers will take effect the next payment.
• When an approver is deleted after a payment is created, this means the payment cannot be approved any more. The users are signalled by the payment-page still showing all original required approvals, but for the deleted approver(s) it will say 'Approver deleted. Create new payment'. Which is what should be done in this case. (Even though non-deleted approvers can technically still approve, collectively they will simply run into the realization that not all approvers can approve any more.)
  • For past payments, we will be able to see the approvers in the payment event log. As these are directly tied to user accounts.

Seeding approver-mode & approver default-role

When seeding, there is an approverMode attribute with 3 values

• none - to be used on production instances
• admin - this is used for local development and testing
• demo - this can be used for demo's.
  • In this case the admin-user will be made approver.
  • Additionally, an approver@example.org user will be created, which is made approver and which will have 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 needs to happen.
  • NOTE: having the approver role is something completely separate from 'being configured as an approver'. The latter is the important thing. And users of any role can be configured as an approver in theory. The default role is just there as an option to clients, as it makes to have a default role for this given the segregation of duties objective.