# Sponsor Bank connector

#### Overview

The `BankConnectorInterface` is designed to provide a unified approach for interacting with different sponsor banks. Custom implementations of this interface allow partners to integrate specific banking APIs without modifying the core G2P Bridge application. An example implementation, `openg2p-g2p-bridge-example-bank-connector`, connects to a simulated bank for testing purposes.

* **Interface Code**: [BankConnectorInterface on GitHub](https://github.com/OpenG2P/openg2p-g2p-bridge/blob/develop/openg2p-g2p-bridge-bank-connectors/src/openg2p_g2p_bridge_bank_connectors/bank_interface/bank_connector_interface.py)
* **Example Implementation**: [Example Bank Connector Repository](https://github.com/OpenG2P/openg2p-g2p-bridge/blob/develop/openg2p-g2p-bridge-bank-connectors/src/openg2p_g2p_bridge_bank_connectors/bank_connectors/example_bank_connector.py)

***

#### Key Components of BankConnectorInterface

The `BankConnectorInterface` requires the following methods:

1. **`check_funds`**
   * **Purpose**: Verifies whether sufficient funds are available in a specific account.
   * **Arguments**:
     * `account_number` (str): The bank account number to check.
     * `currency` (str): Currency type of the account.
     * `amount` (float): Amount to verify for availability.
   * **Returns**: An instance of `CheckFundsResponse`:
     * `status` (FundsAvailableWithBankEnum): Indicates if funds are available (`FUNDS_AVAILABLE`) or not (`FUNDS_NOT_AVAILABLE`).
     * `error_code` (str): Error code if the check fails.
2. **`block_funds`**
   * **Purpose**: Blocks a specified amount in the account for a disbursement cycle.
   * **Arguments**:
     * `account_number` (str): The bank account to block funds in.
     * `currency` (str): Currency of the account.
     * `amount` (float): Amount to block.
   * **Returns**: An instance of `BlockFundsResponse`:
     * `status` (FundsBlockedWithBankEnum): Block status, either `SUCCESS` or `FAILURE`.
     * `block_reference_no` (str): Reference number of the block if successful.
     * `error_code` (str): Error code if blocking fails.
3. **`initiate_payment`**
   * **Purpose**: Sends payment instructions to the bank. This API acknowledges the payment instruction, but the bank processes it asynchronously.
   * **Arguments**: A list of `DisbursementPaymentPayload`, where each payload includes:
     * `disbursement_id` (str): Unique identifier for the disbursement.
     * `remitting_account` (str): Sponsor bank account for the disbursement.
     * `payment_amount` (float): Amount to be paid.
     * `beneficiary_id` (str): Unique ID for the beneficiary.
     * Additional fields include `beneficiary_account`, `beneficiary_name`, and `disbursement_narrative`.
   * **Returns**: An instance of `PaymentResponse`:
     * `status` (PaymentStatus): Payment status, either `SUCCESS` or `ERROR`.
     * `error_code` (str): Error code if the payment fails.
4. **`retrieve_disbursement_id`**
   * **Purpose**: Extracts the disbursement ID from bank transaction records.
   * **Arguments**:
     * `bank_reference` (str): Reference from the bank statement.
     * `customer_reference` (str): Unique disbursement ID in G2P Bridge.
     * `narratives` (str): Transaction narratives from the bank statement.
   * **Returns**: `disbursement_id` (str): Extracted disbursement ID.
5. **`retrieve_beneficiary_name`**
   * **Purpose**: Extracts the beneficiary’s name from bank statement narratives.
   * **Arguments**:
     * `narratives` (str): Narrative fields in the bank statement.
   * **Returns**: `beneficiary_name` (str): Name of the beneficiary.
6. **`retrieve_reversal_reason`**
   * **Purpose**: Identifies the reason for reversal transactions in bank statements.
   * **Arguments**:
     * `narratives` (str): Narrative fields from the bank statement.
   * **Returns**: `reversal_reason` (str): Reason for reversal.

***

#### Data Models and Enums

To implement this interface, several data models and enums are used, imported from the G2P Bridge libraries.

* **`CheckFundsResponse`**: Defines the response structure for fund checks.
* **`BlockFundsResponse`**: Defines the response structure for fund blocking.
* **`DisbursementPaymentPayload`**: Represents the payload for payment initiation.
* **Enums**:
  * `FundsAvailableWithBankEnum`: Represents fund availability statuses.
  * `FundsBlockedWithBankEnum`: Represents fund blocking statuses.
  * `PaymentStatus`: Defines payment outcomes, either `SUCCESS` or `ERROR`.

***

#### Example Implementation Workflow

1. **Define a Custom Connector**: Implement the `BankConnectorInterface` with the sponsor bank’s API details. Use methods like `check_funds`, `block_funds`, and `initiate_payment` to communicate with the bank.
2. **Configure Bank Connector Factory**: Implement `get_bank_connector(sponsor_bank_code: str)` to return an instance of the custom bank connector based on `sponsor_bank_code`.
3. **Testing**: Use the [Example Bank Connector ](https://github.com/OpenG2P/openg2p-g2p-bridge/blob/develop/openg2p-g2p-bridge-bank-connectors/src/openg2p_g2p_bridge_bank_connectors/bank_connectors/example_bank_connector.py)and the[ bank simulator](https://github.com/OpenG2P/openg2p-g2p-bridge-example-bank) for validating your implementation.


---

# 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/tech-guides/bank-connector-interface-guide.md?ask=<question>
```

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.