Bulk payment lets a user pay for multiple items (e.g. five traffic fines) through one master bill. The parent application holds the master bill; child applications each hold an individual bill. The parent's fee is the sum of all children's fees (BULK_CHILD_SUM).
| State | Meaning |
|---|---|
NEW |
User selects items and submits |
PROCESSING_BULK_APPLICATION |
Background job creates one child application per item |
PENDING_BULK_BILL_ID_GENERATION |
Waiting for all children to generate their individual bill IDs |
GENERATING_MASTER_BILL_ID |
All children are ready; generating the master bill |
PAYMENT_PENDING |
Master bill generated; waiting for payment |
PAID |
Master paid; PROCESS_PAYMENT propagated to all children |
PAYMENT_EXPIRED |
Master bill expired before payment |
CANCELLED |
Cancelled; CANCEL propagated to all children |
Triggered as the breaking action on PROCESS_BULK_APPLICATION. Creates one child application per data row from an attached Excel file.
{
"actionType": "CREATE_CHILD_APPLICATION",
"args": {
"serviceCode": "SRVE74EE96A",
"source": "EXCEL_FROM_ATTACHMENT",
"applicationDetailsKeySource": "SUPPORTING_DOCUMENT",
"applicationDetailsMapping": {
"Amount": "mutuellePayment.householdDetails.amount",
"National ID": "mutuellePayment.householdDetails.nationalId"
},
"parentFieldsMapping": {
"YEAR": "mutuellePayment.householdDetails.year"
},
"additionalApplicationSettings": {
"hideFromUserList": true
},
"excludeCurrentApplication": true,
"certificateWithList": false
}
}
| Arg | Description |
|---|---|
serviceCode |
The child service that handles each individual item |
source |
"EXCEL_FROM_ATTACHMENT" — reads rows from an uploaded Excel file |
applicationDetailsKeySource |
"SUPPORTING_DOCUMENT" — the Excel file comes from a form attachment field |
applicationDetailsMapping |
Maps Excel column headers to child form field paths |
parentFieldsMapping |
Maps parent form field keys to child form field paths — used for fields shared across all rows (e.g. year, region) |
additionalApplicationSettings.hideFromUserList |
Set true so children don't appear in the user's application list |
Each child fires this event on the parent once it finishes processing. The parent's endStateCondition defines which child states count as "ready":
{
"endStateCondition": {
"childReadyStates": ["PAYMENT_PENDING", "PROCESSING_FAILED"]
}
}
If all children are in one of the childReadyStates, the parent advances to GENERATING_MASTER_BILL_ID. If not, it stays in PENDING_BULK_BILL_ID_GENERATION and waits for the next notification.
PROCESSING_FAILED is included in childReadyStates so a failed child does not block the master bill — the parent proceeds and the master bill covers only the successfully priced children.
Triggered as the breaking action on TRANSITION (from GENERATING_MASTER_BILL_ID). Generates the master bill whose amount is the sum of all children's individual bill amounts.
{
"actionType": "MASTER_BILL_ID_GENERATION",
"args": {
"excludeCurrentApplication": true,
"certificateWithList": false,
"updateFieldWithDatasetValue": false
}
}
Used in two places:
On PAY — once the master bill is paid, trigger PROCESS_PAYMENT on all children so their individual bills are marked as paid:
{
"actionType": "TRIGGER_CHILD_SERVICE_EVENT",
"args": {
"childrenApplicationEvent": "PROCESS_PAYMENT",
"excludeCurrentApplication": true
}
}
On CANCEL — propagate cancellation to all children:
{
"actionType": "TRIGGER_CHILD_SERVICE_EVENT",
"args": {
"childrenApplicationEvent": "CANCEL",
"excludeCurrentApplication": true
}
}
Set priceType: "BULK_CHILD_SUM" on the parent service's pricing. The system automatically sums the resolved fees of all child applications to produce the master bill amount. No baseValue, dynamicConditions, or formula is needed.
{
"paymentType": "PAID",
"pricing": {
"priceType": "BULK_CHILD_SUM",
"baseValue": null,
"baseCurrency": "RWF",
"dynamicConditions": []
},
"paymentCode": {
"priceType": "FIXED",
"baseValue": "RRA-SERVICE-CODE",
"dynamicConditions": []
},
"paymentAccount": {
"priceType": "FIXED",
"baseValue": "GOR-CG-RWF",
"dynamicConditions": []
},
"paymentMerchant": {
"priceType": "FIXED",
"baseValue": "GOR",
"dynamicConditions": []
},
"paymentExpirationHours": 24
}
The child service uses its own normal pricing (FIXED, DYNAMIC, or PRICE_LOGIC) to compute each individual bill.