create_disbursement_envelope

API Attributes
Direction	Inward
Invoked by	PBMS
Mode	Synchronous
Tables	disbursement_envelope disbursement_envelope_batch_status

disbursement_envelope represents a control object that uniquely defines one instance of disbursement for one disbursement cycle for a benefit program

A benefit program - in one disbursement cycle - will create exactly one disbursement envelope.

This envelope will represent the control object under which all individual disbursements will be made - for one benefit program - for one disbursement cycle.

The object (and corresponding persistent table) will have the following attributes

Object design

disbursement_envelope

Attribute	Datatype
disbursement_envelope_id	Uniquely Identifies the Disbursement Envelope. Primary Key of the Table
benefit_program_mnemonic	The short code that uniquely identifies the benefit program that is creating this disbursement envelope
disbursement_frequency	ENUM - identifies the frequency with which disbursements are effected under this benefit program. Possible Values Weekly Fortnightly Monthly Bimonthly Quarterly SemiAnnually Annually OnDemand
cycle_code_mnemonic	Identifies the particular frequency cycle under which this envelope is being created. Examples - March-2024 or Q1-2024 or Week-1-Jan-2024 or 03-Jan-2024
number_of_beneficiaries	Specifies the number of distinct beneficiaries that this envelope will serve
number_of_disbursements	Specifies the number of discrete disbursements that this envelop will create. In ideal cases, this should equal to the number of beneficiaries, there might be instances where a beneficiary gets more than one disbursement in a single envelope.
total_disbursement_amount	The total of all individual disbursements. This is the control total for one "disbursement cycle - benefit program"
disbursement_currency_code	The ISO Currency code in which the disbursement is going to be effected. This does not necessarily mean that the beneficiaries will be credited (or given cash) in this currency. This only represents the funding side. If beneficiaries are credited in a different account, that currency conversion will happen in the Destination banks (which service the beneficiaries). This currency conversion is of no consequence to the PBMS/Funding Organization/Benefit Program Administration.
disbursement_schedule_date	This is the date on which the Disbursement needs to be effected.
receipt_time_stamp	The timestamp when the envelope was received and persisted by the G2P Bridge
cancellation_status	Enum NOT_CANCELLED CANCELLED
cancellation_time_stamp	The timestamp when the cancellation request was received

disbursement_envelope_batch_status

Attribute	Datatype
disbursement_envelope_id	Uniquely identifies the disbursement envelope. Primary Key
number_of_disbursements_received	The PBMS will first create the disbursement envelope. After that, the PBMS will then dispatch (create) the individual disbursements under the envelope. Being a social benefit program, each envelop can potentially target a large population - running into hundreds of thousands (perhaps even millions). The PBMS is expected to do this disbursement in batches. This attribute - is the control - that keeps track of the number of disbursements that have actually been received by the G2P Bridge from the PBMS. Once this number reaches the number specified by the disbursement_envelope.total_number_of_disbursements, the system will not accept any more disbursements from the upstream PBMS platform.
total_disbursement_amount_received	This represents the sum of individual disbursements received. Once this number matches the number specified in the envelope (control figure), the system will not accept any more disbursements from the upstream PBMS
funds_available_with_bank	Enum PENDING_CHECK FUNDS_NOT_AVAILABLE FUNDS_AVAILABLE
funds_available_latest_timestamp
funds_available_latest_error_code
funds_available_attempts
funds_blocked_with_bank	Enum PENDING_CHECK FUNDS_BLOCK_SUCCESS FUNDS_BLOCK_FAILURE As and when PBMS ships the disbursements, this field will be updated to "Pending" - once all the disbursements are received (the received number of disbursements equal to the declared number of disbursements) Pending -> Complete - This will be updated by a background job that creates "Hold Funds" with the Sponsor Bank.
funds_blocked_time_stamp
funds_blocked_latest_error_code
funds_blocked_attempts
funds_blocked_reference_number	This is the Amount Block (Funds Hold) Reference number - returned by the Sponsor Bank. This Reference number uniquely identifies the Amount Block that has been placed against the Disbursement Envelope.
id_mapper_resolution_required	TRUE / FALSE This value is taken from the helper table - benefit_program.id_mapper_resolution_required
number_of_disbursements_shipped	The G2P Bridge will ship the disbursements to the Sponsor Bank in batches (Note that the volume of disbursements is expected to be in 100s of 1000s or perhaps even millions, batch processing will be necessary). This attribute is updated as and when batches of disbursements are successfully shipped After all disbursements are shipped, this number will equal to the envelope.number_of_disbursements
number_of_disbursements_reconciled	The number of disbursements - where we have received the corresponding "Debit" to the program account in the sponsor bank
number_of_disbursements_reversed	The number of disbursements - where we have received the corresponding "Debit" to the program account in the sponsor bank - as well as - a subsequent reversal to the "Debit" The Debit reversal has been effected in the sponsor bank due to a reject from the beneficiary's bank (destination bank)

Business logic

Will result in persistence of 1 record each in the tables - disbursement_envelope and disbursement_envelope_batch_status

Validations & exceptions

1. disbursement_schedule_date should be greater than today + disbursement_sla_days (configuration)

2. disbursement_currency_code should be equal to benefit_program.disbursement_currency_code

3. disbursement_envelope_id should be unique

4. benefit_program_mnemonic should exist in benefit_program

5. number_of_beneficiaries - valid non zero integer

6. number_of_disbursements - should be greater or equal to number_of_beneficiaries

7. total_disbursement_amount - valid non zero number