Operations

Reusing Product Configuration

p# Reusing product configuration

Shared integration connections

Open Admin → Shared Integrations to configure a provider connection and its credentials once for your organization. In each product’s Integrations configuration, select that connection and configure the capability, workflow step, required flag, timeout, and retries. Credentials stay in the shared connection; product gates reference it. Changes to a connection affect products using it.

Available adapters

The connection form is driven by the adapter manifest (GET /integrations/adapters): each adapter declares its settings and credential fields, and the form renders them dynamically. Advanced JSON editors remain available for fields outside the manifest.

Credentials are encrypted and write-only: saving replaces them, but they are never returned to the browser.

Integration gates in product workflows

An integration gate is a workflow step of type Integration (INTEGRATION). Selecting it locks the step to AUTOMATED mode with the integration_gate handler; staff cannot manually complete the step to bypass the provider call.

1. In Product Configuration → Workflow, add a step of type Integration and give it a descriptive step key (for example ndasenda_id_check or netone_collection).
2. In Product Configuration → Integrations, add a gate requirement: workflow type LOAN_APPLICATION, the same step key, the capability, the shared connection, the required flag, and per-gate Timeout (seconds) and Retry limit settings.

Capabilities include IDENTITY_VERIFICATION, MANDATE_REGISTRATION, MANDATE_CANCELLATION, PAYMENT_INITIATION, DISBURSEMENT_EXECUTION, ACCOUNT_LOOKUP, PAYMENT_STATUS_CHECK, REPAYMENT_IMPORT, AFFORDABILITY_CHECK, and DISBURSEMENT_STATUS_CHECK. A provider only supports the operations its adapter implements; the manifest lists them.

Execution payload

When a gate step runs, the handler builds a provider-neutral payload from the application and borrower record; adapters translate it into provider calls:

• Identity/contact: id_number, mobile_no, recipient_mobile, recipient_id_number, borrower_name, borrower_surname
• Employment: employer_name, ec_number, payroll_number (from the borrower’s current employment record)
• Money: amount (approved amount when set, otherwise requested), installment_amount (the active proposal’s computed payment), currency (product currency)
• Context: application_id, application_number, product_id, workflow_task_id, requested_term, requested_term_unit, purpose
• Application custom fields merge last and can override any key, including supplying a full records batch for mandate operations.

Executions are durable and idempotent: one execution per required capability, retried within the gate’s retry limit, with no provider call inside the workflow transaction.

Disbursement and repayment through providers (payment intents)

Provider money movement does not use workflow gates. A disbursement or a customer repayment is a runtime payment intent processed by a background worker against the same shared connection.

• Disbursement (B2C payout): create the loan’s disbursement record (mobile-money method with the wallet number), then start a provider intent from the disbursement screen — POST /servicing/disbursements/{id}/intent with the provider connection and optional recipient_mobile/recipient_id_number. NetOne resolves the recipient ID through the subscriber lookup when omitted and defaults business_type to loan disbursement. A successful provider result is the only path that confirms the transfer and activates the loan.
• Customer repayment (C2B collection): from the loan’s repayment area, choose the provider rail, amount, and mobile number — POST /servicing/payments/intents. NetOne pushes a USSD prompt to that number; the payer approves with their PIN. The posted repayment lands on the loan only after the provider confirms, so a customer can pay from any Zimbabwean NetOne wallet — a different phone or a relative’s line works.
• Traditional methods: tenants without provider integrations (or loans paid in cash/bank transfer) record payments through the normal payment capture screens; nothing above is required.

Intent status can be polled at GET /servicing/payments/intents/{id}; retries honor the intent’s retry limit and timeout.

Provider-specific behavior worth knowing

• NetOne normalizes Zimbabwean mobiles to the 7XXXXXXXX format (+263…, 263…, 0… all accepted) and rejects non-Zim numbers before calling the API. Before a C2B push or B2C payout it verifies the number is an active, certified subscriber via the customer lookup — configure customer_lookup_url or the payment fails at that check. notify_url is an optional webhook for the final order result; status polling continues regardless.
• Ndasenda obtains its OAuth token at runtime from the username/password credentials; the static security_token credential is sent in request bodies. deduction_code is issued per employer by Ndasenda — required for mandate operations, not for ID checks. Mandate records are built automatically from borrower fields when no explicit records batch is supplied: national ID, EC/payroll numbers, the proposal installment as the deduction amount, and the requested term as the mandate end date. When the loan closes, a MANDATE_CANCELLATION intent is queued automatically against the same connection to stop deductions.

Workflow and approval templates

In a product’s Workflow Configuration or Approval Chain builder:

1. Configure the workflow or approval rules once.
2. Enter a template name and choose Save draft as shared template.
3. Open another product, choose the template, and click Apply to draft.
4. Adjust the draft for that product, then save. Publish workflows explicitly when ready.

Applying a template replaces the currently displayed draft. It does not save or publish automatically. A template is a snapshot: later product edits do not modify it or other products. To reuse a revised configuration, save another template with a descriptive name.

Workflow templates contain workflow configuration only. Configure the product’s approval chain and integration gates separately; approval chains have their own reusable templates. Product IDs, publication state, and credentials are not copied into templates.

Templates are isolated to the current tenant and use the same validation as product drafts. Existing product configurations are preserved.

Deployment

Apply tenant migrations 000266_product_configuration_templates and 000268_borrower_employment_deduction_fields before using the template library and payroll-mandate fields, then deploy the backend and frontend together. No existing configuration data needs to be converted.