diff --git a/g2p-bridge/development/design-specifications/example-bank/openg2p-g2p-bridge-example-bank-models.md b/g2p-bridge/development/design-specifications/example-bank/openg2p-g2p-bridge-example-bank-models.md index 5f425736..1626e7a1 100644 --- a/g2p-bridge/development/design-specifications/example-bank/openg2p-g2p-bridge-example-bank-models.md +++ b/g2p-bridge/development/design-specifications/example-bank/openg2p-g2p-bridge-example-bank-models.md @@ -21,20 +21,24 @@ This is a library project - that contains all the sqlalchemy models and pydantic ### **account** -| Attribute | Deesreption | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| account\_number |

Primary Key - will hold the Account that funds the benefit program
In the Sponsor Bank, this is the account number that will be debited for every disbursement

The corresponding credit will be either to the beneficiary_account (if the beneficiary account is serviced by the sponsor bank itself)

OR

The corresponding credit will be to the clearing account Nostro (mirror of the sponsor bank's account with the clearing house)

| -| account\_holder\_name | Should identify the Benefit Program that uses this account | -| account\_currency | The currency in which funds are held in the account | -| book\_balance | This is the ledger balance in the account | -| available\_balance |

This is the available balance (funds available for use for disbursements)
available_balance = book_balance - blocked_amount

| -| blocked\_amount |

This is the total amount that has been reserved (earmarked) by the program for specific purposes.

The G2P Bridge - blocks the entire envelope amount - for every disbursement_envelope.

The sponsor bank - creates an Amount Block for every block request. These amount blocks are available in the table - fund_blocks. The sum total of all records in fund_blocks equals this blocked_amount

| +Table used - to maintain accounts for benefit programs. This table will also maintain the book balance, available balance and funds blocked for these program accounts. + +| Attribute | Description | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| account\_number |

Unique Index - will hold the Account that funds the benefit program
In the Sponsor Bank, this is the account number that will be debited for every disbursement

The corresponding credit will be either to the beneficiary_account (if the beneficiary account is serviced by the sponsor bank itself)

OR

The corresponding credit will be to the clearing account Nostro (mirror of the sponsor bank's account with the clearing house)

| +| account\_holder\_name | Should identify the Benefit Program that uses this account | +| account\_currency | The currency in which funds are held in the account | +| book\_balance | This is the ledger balance in the account | +| available\_balance |

This is the available balance (funds available for use for disbursements)
available_balance = book_balance - blocked_amount

| +| blocked\_amount |

This is the total amount that has been reserved (earmarked) by the program for specific purposes.

The G2P Bridge - blocks the entire envelope amount - for every disbursement_envelope.

The sponsor bank - creates an Amount Block for every block request. These amount blocks are available in the table - fund_blocks. The sum total of all records in fund_blocks equals this blocked_amount

| ### **fund\_blocks** +Table used - to maintain funds blocks for program accounts. Every successful funds block request will be identified by a "block\_reference\_no" and will have exactly one record in this table. + | Attribute | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| block\_reference\_no | Unique Id - for every block transaction. Every request for an amount block - generates this unique Id. | +| block\_reference\_no | **Unique Index - for every block transaction.** Every request for an amount block - generates this unique Id. | | account\_number | The account funding the benefit program | | currency | The currency in which the account operates | | amount |

The amount that has been blocked under this block_reference_no.

The g2p-bridge subsystem requests an amount block for the total envelope amount.

This amount reflects that total envelope amount in this scenario

| @@ -42,39 +46,41 @@ This is a library project - that contains all the sqlalchemy models and pydantic ### initiate\_payment\_batch\_requests -| Attribute | Description | -| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| batch\_id |

The G2P Bridge will initiate payments in batches.
Each API invocation (initiate_payment) will result in a creation of a unique batch_id.
All individual disbursements (payments) in that request will be grouped under this batch_id.

| -| accounting\_log\_attempts |

The actual payment itself (generating book keeping entries) is handled asynchronously. A celery beat picks up all PENDING batches and delegates the batch_id to a task.
This attribute - keeps a count of these attempts.

| -| accounting\_status |

PENDING, PROCESSED
A celery beat picks all PENDING records and delegates the batch_id to a celery worker.
The worker picks up the individual payment records for this batch_id and effects book keeping entries for the "remitting_account"

| +When the g2p-bridge initiates a payment request for a bunch of disbursements, all the disbursements in a single request are treated as a single batch. A batch\_id is allocated to this group of disbursements. A batch\_id will have a single record in this table. Further downstream processing in terms of generating book keeping entries will be processed together for a batch\_id. + +| Attribute | Description | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| batch\_id |

Unique Index.
The G2P Bridge will initiate payments in batches.
Each API invocation (initiate_payment) will result in a creation of a unique batch_id.
All individual disbursements (payments) in that request will be grouped under this batch_id.

| +| accounting\_log\_attempts |

The actual payment itself (generating book keeping entries) is handled asynchronously. A celery beat picks up all PENDING batches and delegates the batch_id to a task.
This attribute - keeps a count of these attempts.

| +| accounting\_status |

PENDING, PROCESSED
A celery beat picks all PENDING records and delegates the batch_id to a celery worker.
The worker picks up the individual payment records for this batch_id and effects book keeping entries for the "remitting_account"

| ### initiate\_payment\_requests -| Attribute | Description | -| ------------------------------------- | ----------- | -| batch\_id | | -| payment\_reference\_number | | -| remitting\_account | | -| remitting\_account\_currency | | -| payment\_amount | | -| payment\_date | | -| funds\_blocked\_reference\_number | | -| beneficiary\_name | | -| beneficiary\_account | | -| beneficiary\_account\_currency | | -| beneficiary\_account\_type | | -| beneficiary\_bank\_code | | -| beneficiary\_branch\_code | | -| beneficiary\_mobile\_wallet\_provider | | -| beneficiary\_phone\_no | | -| beneficiary\_email | | -| beneficiary\_email\_wallet\_provider | | -| narrative\_1 | | -| narrative\_2 | | -| narrative\_3 | | -| narrative\_4 | | -| narrative\_5 | | -| narrative\_6 | | +| Attribute | Description | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| batch\_id |

Index. Not unique.
A single batch_id will have many disbursements. Disbursements initiated from g2p-bridge in a single API invocation will be grouped together under a single batch_id.

| +| payment\_reference\_number |

Unique Index

Every disbursement is treated as an individual payment request.
Every payment request is uniquely identified by a payment_reference_number
The g2p-bridge populates "disbursement_id" as the payment_reference_number

| +| remitting\_account |

This is the account that is debited for this payment request.
In the g2p-bridge scenario, this account will be the program's funding account.

| +| remitting\_account\_currency | This is the currency in which the remitting\_account operates. This will typically be the local currency of the nation, in which this benefit program runs. | +| payment\_amount | The payment amount, the amount that will be transferred to the beneficiary's account. In the g2p-bridge scenario, this amount will be the disbursement amount. | +| payment\_date | | +| funds\_blocked\_reference\_number | | +| beneficiary\_name | | +| beneficiary\_account | | +| beneficiary\_account\_currency | | +| beneficiary\_account\_type | | +| beneficiary\_bank\_code | | +| beneficiary\_branch\_code | | +| beneficiary\_mobile\_wallet\_provider | | +| beneficiary\_phone\_no | | +| beneficiary\_email | | +| beneficiary\_email\_wallet\_provider | | +| narrative\_1 | | +| narrative\_2 | | +| narrative\_3 | | +| narrative\_4 | | +| narrative\_5 | | +| narrative\_6 | | ### accounting\_logs