Bank Connectors
Last updated
Last updated
Copyright © 2024 OpenG2P. This work is licensed under Creative Commons Attribution International LicenseCC-BY-4.0 unless otherwise noted.
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
account_number
string
currency
string
amount
number
returns
funds available status
FUNDS_AVAILABLE FUNDS_NOT_AVAILABLE
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
block_result
SUCCESS or FAILURE
block_error_code
Error in case of FAILURE
block_result_reference
The block reference in case of SUCCESS
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
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
response
SUCCESS or FAILURE
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
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
narratives [0] to [5]
The 6 lines of narratives - 0 to 5 - Field 86 of the Account Statement
returns
beneficiary_name
Depending on the sponsor bank - we need to extract the beneficiary name from one of the narratives fields
narratives [0] to [5]
The 6 lines of narratives - 0 to 5 - Field 86 of the Account Statement
returns
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.
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
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
