Interfaces

openg2p-g2p-bridge - Technical architecture

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