Refer to the Technical architecture. As shown in the figure, all outward APIs towards a Sponsor bank are abstracted through an interface. This interface is in the library project - **openg2p-g2p-bridge-bank-connectors**
There is also an implementation of the interface (openg2p-g2p-bridge-example-bank-connector), that provides a reference implementation. This connector connects to a simulator application. The simulator application (openg2p-g2p-bridge-example-bank-api) simulates a Sponsor bank.
The interface, the connector factory and the example-bank-connector - together are packaged into a separate git repository - **openg2p-g2p-bridge-example-bank**
The interface defines the following APIs
### 1. check\_funds
| Arguments | Type |
| --------------- | ------ |
| account\_number | string |
| currency | string |
| amount | number |
returns
| attributes | Type |
| ---------------------- | ------------------------------------------------ |
| funds available status |
FUNDS\_AVAILABLE FUNDS\_NOT\_AVAILABLE
|
### 2. block\_funds
| Arguments | Description |
| --------------- | -------------------------------------------------------------------------------------- |
| account\_number | The program funding account with the sponsor bank |
| currency | The currency of the funding account |
| amount | The total envelope amount - required for complete disbursal in that disbursement cycle |
returns
| Attributes | Description |
| ------------------------ | -------------------------------------- |
| block\_result | SUCCESS or FAILURE |
| block\_error\_code | Error in case of FAILURE |
| block\_result\_reference | The block reference in case of SUCCESS |
### 3. initiate\_payment
It will take a collection of the following structure (payment structure)
This API will only acknowledge receipt of a payment instruction. The actual payment will be effected by the bank asynchronously
| Arguments | Description |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| disbursement\_id | This is the unique disbursement id - that identifies a single disbursement inside an envelope |
| remitting\_account | This is the account in the Sponsor bank - from where the funds are remitted to the beneficiaries |
| remitting\_account\_currency | The currency of the funding account |
| payment\_amount | The disbursement amount |
| funds\_blocked\_reference\_number | The block\_reference\_number - that identifies the amount\_block placed in the bank (funds earmarked for this envelope) |
| beneficiary\_id | The beneficiary ID that uniquely identifies the beneficiary in that benefit program - this ID should come from the upstream MIS/PBMS systems |
| beneficiary\_name | The name of the beneficiary |
| beneficiary\_account | The account number of the Beneficiary - in the destination financial service provider |
| beneficiary\_account\_currency | This should ideally be the same as the funding account currency - typically the local currency of the nation |
| beneficiary\_account\_type |
BANK\_ACCOUNT MOBILE\_WALLET EMAIL\_WALLET
|
| beneficiary\_bank\_code | The Bank code (destination bank) in which the beneficiary account is serviced (applicable for BANK\_ACCOUNT) |
| beneficiary\_branch\_code | The branch code (of the destination bank) in which the beneficiary account is serviced (applicable for BANK\_ACCOUNT) |
| beneficiary\_mobile\_wallet\_provider | The code that identifies the service provider for the mobile wallet (applicable for MOBILE\_WALLET) |
| beneficiary\_phone\_no | The mobile number where the beneficiary will be credited (applicable for MOBILE\_WALLET) |
| beneficiary\_email | The email address where the beneficiary will be credited (applicable for EMAIL\_WALLET) |
| beneficiary\_email\_wallet\_provider | The code that identifies the service provider for the email wallet (applicable for EMAIL\_WALLET) |
| disbursement\_narrative | Any narrative about the disbursement that will help in reconciliation with the account statement of the funding account |
| benefit\_program\_mnemonic | The program identifier - This can be used as a narrative by the destination bank - so that the beneficiary is able to identify disbursements from the benefit program |
| cycle\_code\_mnemonic | The cycle identifier - that can be potentially used as a narrative by the destination bank - useful for the beneficiary to identify disbursement payments |
| payment\_date | The date on which the disbursement needs to be effected |
returns
| Attribute | Description |
| --------- | ------------------ |
| response | SUCCESS or FAILURE |
### 4. retrieve\_disbursement\_id
| Arguments | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bank\_reference |
This is the reference number of the payment - that has been assigned by the sponsor bank. The part that follows the "//" in field 61
|
| customer\_reference |
This is the reference number (unique for every remittance/disbursement) that has been provided by the g2p-bridge application. In our case - it is the disbursement\_id The part that precedes the "//" in field 61
|
| narratives \[0] to \[5] | The 6 lines of narratives - 0 to 5 - Field 86 of the Account Statement |
returns
| Attribute | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| disbursement\_id |
Depending on the sponsor bank - we need to extract this disbursement id from one of the three attributes
In most cases - it should be the customer\_reference - because that is the customer\_reference (disbursement\_id)
The interface abstraction exists to take care of those outlier cases - where the sponsor bank has implemented it differently
|
### 5. retrieve\_beneficiary\_name
| Arguments | Description |
| ----------------------- | ---------------------------------------------------------------------- |
| narratives \[0] to \[5] | The 6 lines of narratives - 0 to 5 - Field 86 of the Account Statement |
returns
| Attribute | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| beneficiary\_name | Depending on the sponsor bank - we need to extract the beneficiary name from one of the narratives fields |
### 6. retrieve\_reversal\_reason
| Arguments | Description |
| ----------------------- | ---------------------------------------------------------------------- |
| narratives \[0] to \[5] | The 6 lines of narratives - 0 to 5 - Field 86 of the Account Statement |
returns
| Attribute | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| retrieval\_reason |
For reversal transactions
(where the initial debit to the funding account was subsequently reversed - after a transaction was returned from the destination bank with an error)
the reason for reversal has to be extracted from one of the narratives fields.
|
### Bank Connector Factory
This Factory will return a BankConnector Interface
This BankConnector class will implement the BankConnector Interface
The Factory will return the Connector based on the "benefit\_program.sponsor\_bank\_code"
def get\_bank\_connector (sponsor\_bank\_code : string) -> BankConnectorInterface
### Example Bank Connector
The git baseline includes a connector that connects with the Example Bank (a bank simulator application). The Example Bank Connector - implements all the methods specified by the BankInterface
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.openg2p.org/products/g2p-bridge/development/design-specifications/interfaces.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.