# Overview In its daily workings, governments across local, state and national levels make various payments to people of a country. This may be in the form of subsidies, pensions, scholarships, incentives during emergencies and more. Citizens may choose to receive these payments in different ways such as through cash, bank transfers, mobile wallets, prepaid vouchers, etc. Each government entity who is a facilitator of any of these g2p benefit schemes is required to build its own system to verify individuals, authenticate transactions and transfer money. They often have to communicate across departments to accumulate all the data needed to make an informed decision regarding the eligibility for a payment transfer, and then across another set of departments to actually disburse that payment. In order to coordinate this monumental, yet routine effort, duplication of systems, effort and resources takes place at every level of government and across departments. It also causes delays, high costs, leakages and loss of transparency, as a result of which funds don’t always reach their intended beneficiaries. Creating a centralised storage of data doesn’t work either because it creates honeypots that pose large security risks, have no formal method for setting accountability of data-updation and require building entirely new systems. This solution follows the traditional mindset of digitisation ie: taking things ‘online’ without accounting for political realities, human centric design, different speeds and degrees of adoption, and a future-focused, innovation mindset. This is not what Digital Public Infrastructure refers to. **A G2P DPI is about building an overarching architecture that ensures interoperability, inclusion, privacy, security, autonomy and asynchronous adoption by design.** The common steps of executing any g2p payment includes: 1. Checking for eligibility of the beneficiaries according to pre-set scheme criteria using data from federated functional registries 2. Authenticating the identity of the eligible beneficiaries using online/offline, self/assisted modes 3. Mapping the authenticated, eligible beneficiaries to a store of value of their choice in which they choose to receive these payments using multiple payment rails The easiest way to increase the efficiency, effectiveness and security of these g2p payments is to build a secure, decentralised architecture that provides common building blocks (solving for the 3 points listed above), that individual departments can then customise on top. This is what G2P Connect solves! G2P connect enables the creation of a shared infrastructure in a country that different agencies can use to deliver any kind of government to person payment digitally end-to-end. This includes establishing the identity of the beneficiary, eligibility, enrolment, mapping IDs to bank accounts, disbursement, last mile cash access and scheme monitoring. **G2P Connect is an open source effort to enable government-to-person digital payments built through interoperable** [**standards**](https://g2p-connect.github.io/specs/dist/index.html) **and design blueprints** G2P Connect enables policy makers across various departments to ‘talk’ to each other without revealing any sensitive information. This means that: * Every department is allowed to own its own information. They simply standardise the information using a common identifier for each individual and link their database through APIs. * Other departments that require information to make a decision regarding a transfer, can specify their eligibility criteria (which can freely change with the times) as they do currently * All systems are standardised to share telemetry information for policy makers to observe key performance metrics and to make informed decisions Thus, autonomy, freedom of choice and change, and simplification of the process is ensured at each step. The process of a transaction carried out through G2P works like this (NOTE: this is a generalised flow, individual transactions may vary depending on sector of implementation): 1. An individual will request funds from the scheme he is interested in and specify his store of value. He will provide his identifier number and may be required to do additional authentication (such as through OTPs or biometrics) 2. His identifier number will be sent to the issuing department and a request will be logged. 3. According to the eligibility criteria set out by the issuing department, this identifier number will be ‘mapped’ to the various data sources across government databases that host this relevant information. This will be done through the common APIs. 4. The interface will not transfer any data from one store house to another, but simply return a ‘yes/no’ answer about whether the individual has met the eligibility criteria or not. The answers across databases will be compiled and a final ‘yes’ or ‘no’ answer will be communicated to the requesting department/agency. 5. If the individual is eligible, then this identifier number will connect to the store of value he has chosen. The social benefit sponsoring department simply has to authorise the transfer and the funds will reach the beneficiary’s account. This allows for a secure, quick transfer of funds from g2p across use cases and departments in a federated, using near real time info and in privacy protecting manner. G2P Connect also provides a range of other benefits for beneficiaries: * Beneficiaries get easy, secure, quick access to funds in cases of emergencies by undertaking minimal steps (sometimes as easy as entering their identifier number on the relevant government portal!) * Beneficiaries get to authorise the sharing of their data with specific departments for specific purposes. * Verification and authentication of transactions (through timestamps and digital signatures) prevent fraud from being carried out by citizens and prevent errors from the government’s side. # Solution Blueprint ##

G2P Connect Solution Blueprint

## **Components of G2P Connect solution blueprint:** 1. Foundational Digital ID System 2. Trusted Data Sharing & Digital Credentialing Infrastructure 3. Civil & Other Federated Registries 4. [ID-Account Mapper](/protocol/interfaces/beneficiary-management/mapper-architecture) 5. Social Program & Beneficiary Management 6. Payment & Settlement Switch 7. Bank/Mobile-wallet System 8. Last Mile Cash-In/Cash-Out System 9. Unified View for Policy Makers 10. Unified View for Beneficiaries 11. Banking/Wallet Interface Systems G2P Connect [APIs](https://g2p-connect.github.io/specs/release/index.html) # Overview G2P Connect API Specifications is an open source effort to standardise the key integrations across functional categories defined in G2P Connect Technology Architecture [Blueprint](/g2p-connect/solution-blueprint). G2P Connect Integration Specification assumes interactions between various DPI solution providers (i.e DPGs, Proprietary/Existing systems) may vary due to country specific policies and availability of digital/banking/last mile connectivity infrastructure. For e.g., > a. Few countries may have centralised payment switch operated by central bank while others may operate directly with financial institutions.\ > b. Countries may decide to manage ID to Financial Address mapping either at Payment Switch layer or Financial Institution(s) or Beneficiary Management Platforms or an independent entity.\ > c. Countries may not have a foundational de-duplicated digital id. G2P Connect is flexible to enable DPI solution providers (i.e DPGs, Proprietary/Existing systems) to **orchestrate** flows based on various use case scenarios that are specific to country's operating requirements. ## Objectives The following are key objectives of G2P Connect Specifications: 1. Focus on G2P Connect solution blueprint - enable seamless integration between solutions relevant to end to end G2P payment scope keeping policy maker and beneficairy at the center. 2. Flexible to accomodate existing standards where applicable, e.g., OAuth2, OpenID Connect, W3C Verifiable Crendentialing. 3. Standardise message envelope to support **harmonised** integrations across various solutions with key features: * Transport layer agnositc communication * Async based processing with retry/polling support * Offline processing capability enabling store & forward * Batch processing * Support plug n play for other payloads e.g. OpenID / country specific custom data or verifiable credentials * Support for digitally signed and encrypted payloads 4. Enable integration between existing proprietary, DPI/DPGs or country specific custom in-house solutions. 5. Focus is on standardising core interfaces and NOT on implementation. 6. Each interface act as a connector between solutions and allow country implementations to realize various use cases. ## Message Structure All communications using G2P Connect specifications have following structure: | Field | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------- | | signature | element holding signature to prove non-repudiability of payload (header & message) between sender & receiver | | header | common header to track messages between sender & receiver for traceability and to track message delivery at transport layer | | message | message to hold transaction request/response entities | ```json "signature": "Signature: namespace=\"g2p\", kidId=\"{sender_id}|{unique_key_id}|{algorithm}\", algorithm=\"ed25519\", created=\"1606970629\", expires=\"1607030629\", headers=\"(created) (expires) digest\", signature=\"Base64(signing content)" ``` ```json "header": { "version": "0.1.0", "message_id": "123456789020211216223812", "message_ts": "2022-12-04T18:01:07+00:00", "action": "disburse", "sender_id": "10089", "sender_uri": "https://pymts.sender.org/g2p/callback/on-disburse", "receiver_id": "52077", "receiver_uri": "", "total_count": 21800, "encryption_algo": "aes+rsa" } ``` ## Identifiers 1. message\_id: scope of message\_id in header is to track paylaod delivery between sender and receiver. 2. transaction\_id: scope of transaction\_id in message is to uniquely corelate business request(s). 3. reference\_id: scope of the reference\_id in message domain entity is to corelate individual business request. ## Normative Addressing 1. To enable payment processing using various store of value accounts, G2P Connect uses normative addressing format and refer these as financial addresses (fa). e.g. payer fa, payee fa etc., 2. To enable integration with various identity systems/registries all beneficiary id's are also represented in normative formats. ```yaml type: string description: "
1. Financial address is case insensitive normative represenation of a store of value account represented as id-type:id@provider
2. Every payer/payee financial address must resolve to an actual store of value account number for processing the payment instruction
3. It is recommended the mapping between id and store of value account details to be held only at final store of value entity and intermediaries can hold 3. Few examples:
- token@id-provider e.g token:12345@mosip
- uid@pymt-rail e.g uid:12345@mosip
- vid@id-provider e.g vid:12345@PhilID
- mobile@mobile-provider e.g mobile:12345@m-pesa
- account-id@bank-psp-code e.g account:12345@gtbank
- account-no@ifsc-code.ifsc.npci e.g account:12345@HDFC0000001.ifsc.npci
- user-id@psp-code e.g. joeuser@gtbank
- token@psp-code e.g token:123456@sbi
- code@purpose-code.voucher-provider e.g voucher:12345@food.sodexo
- cdbc-id@cdbc e.g. 12345@DCash" format: "^[a-zA-Z0-9.-]+@[a-zA-Z0-9.-]+$" example: "token:12345@gtbank" ``` ```yaml type: string description: "
1. Beneficiary id is case insensitve normative represenation as id-type:id@provider
2. This will enumerate foundational and functioanl id's to easily resolvable addressess
3. This property is intended to unambiguously refer to an object, such as a person, organization, etc.,
4. Few examples:
- id@identifier-type.id-provider e.g token:12345@mosip, vid:12345@philid
- id@civil-registry.issuing-agency e.g id:12345@rwanda, id:12345@ejanma.karnataka
- id@functional-identifier.issuing-agency e.g id:12345@voter.Rwanda, id:12345@DL.karnataka, mobile:12345@fruits.karnataka
Note: id provider should be made configurable and solutions should adapt to the local jurisdiction and policies.
e.g fruits.karnataka represents farmer registry in karnataka state govt.
" format: "^[a-zA-Z0-9.-]+@[a-zA-Z0-9.-]+$" example: "vid:12345@mosip" ``` ## Transport Protocol 1. G2P Connect Integration Specification is designed to be transport layer agnostic viz. JSON entities over HTTPS, pub/sub event based messaging or file exchanges. 2. header field helps in reliable exchange at transport layer between sender and receiver. ## Communication Protocol 1. Most of the interactions are asynchronous in nature between sender/receiver. 2. Sender initiates with message\_id and receiver synchronously acknowledge with receipt of the message with ACK/NACK/ERR status codes. 3. ACK represent async callback, NACK represent end of exchange and ERR represent message couldn't be successfully parsed for processing. 4. For all async /xxxx service end points, Senders are required to implement /on\_xxxx end points to receive callback responses. 5. All services implement /{service}/txn/status and /{service}/txn/on\_status end points to poll and fetch responses of previously attempted requests using transaction\_id or reeference\_id 6. For service end points that are exposed to end user interfacing UX channels where call back processing becomes challenging or technical not-feasibile, receiver systems are required to implement GET status api's. Sender systems may poll to GET transaction status/detailed information and limit count of individual business requests (i.e reference\_id's). ## File based processing 1. For file based exchange it is recommended to use the JSON payloads. JSON format is hierarchal, self describing for easy integrations. 2. If a country has use case to use other formats (e.g. CSV) then it is recommended to use the same JSON definitions by flattening each entity as a file row. In this scenario, signature element shall be part of the first row, header elements in second row followed by one or more message array listed in each row. nested objects are to be flatted in the same row. 3. Above logic shall work for encrypted request element as well. 4. File exchange may happen using HTTPS, sFTP or any other file exchange mechanisms. ## Event based processing 1. G2P Connect JSON based request/response entities shall work as events over messaging infrastructure. 2. Trusted sender and receiver systems on a network should create pub/sub end points. ## Data Formats 1. All dates and timestamps are represented in RFC3339 format including timezone e.g., 2022-12-04T18:01:07+05:30 2. All currency codes represented in ISO 4217 format # Terminology | Term | Description | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | sender | Initiator of request by any application/service/system/platform using G2P Connect compliant interfaces | | receiver | Receive of request by any application/service/system/platform using G2P Connect compliant interfaces and either process or forwards downstream with minimal or no validations as a Sender | | payer | a person or organization that gives money from a store of value account | | payee | a person or organization that receives money into a store of value account | | fa | Financial Address to uniquely identify person/organization to a store of value account | | Scheme Mgmt or Program Mgmt | Interchangeably used to define issuance mechanisms of a social assistance | | Beneficiary | a person or organization that receives money as part of social assistance | # Interfaces ### G2P Connect Core Interfaces Below core interfaces & codes help to easily identity functional areas for implementation partners. | Interface (Code) | Version | Release Date | Description | | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | ------------ | ------------------------------------------------ | | [Identity](/protocol/interfaces/identity) (ID) | [0.1.0](https://g2p-connect.github.io/specs/dist/g2p-identity.html) | Draft | APIs to access authentication & eKYC services | | [Credentialing](/protocol/interfaces/credentialing) (CRED) | [0.1.0](https://g2p-connect.github.io/specs/dist/g2p-credential.html) | Draft | Issue, manage digital verifiable credentials | | [Registries](/protocol/interfaces/registries) (REG) | [0.1.0](https://g2p-connect.github.io/specs/dist/g2p-crvs.html) | Draft | Subscribe, Notify and Search civil registry info | | [Financial Address Mapper](/protocol/interfaces/beneficiary-management/mapper-specs) (FAM) | [0.1.0](https://g2p-connect.github.io/specs/dist/g2p-mapper.html) | Draft | Manage ID to financial address mapper registry | | [Disbursement](/protocol/interfaces/social-program-management/disbursement) (DSBT) | [0.1.0](https://g2p-connect.github.io/specs/dist/g2p-disburse.html) | Draft | Payment disbursements | | Social Program Management (SPM) | 0.1.0 | Draft | Manage social programs | | Beneficiary Management (BM) | 0.1.0 | Draft | Manage beneficiaries | ### Other Interfaces | Interface (Code) | Version | Release Date | Description | | --------------------------------------------------------- | ------- | ------------ | --------------------------------------- | | [Authorization](/protocol/security/authorization) (AUTHZ) | 0.1.0 | Draft | OAuth2 compliant authz token to connect | # Identity ### Overview 1. G2P Connect recommends Gov Stack published Identity Building Block [specifications](https://govstack.gitbook.io/bb-identity/8-apis-and-services) 2. Below G2P Connect API's with batch / async support is an additional option for implementing systems to consider to integrate with digital ID systems. ### References 1. API specification link 2. Discussion [thread](https://github.com/G2P-Connect/.github/discussions) ### Interface List | Interface ID | End Point | Description | | ------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------- | | ID-VRFY | POST /identity/verify | Authenticate using otp, demo or bio factors | | ID-ON-VRFY | POST /identity/on-verify | Authentication response through callback | | ID-TXNSTS | POST /identity/txn/on-status | Perform async status check of previous identity transanctions using transaction\_id and/or reference\_id(s) | | ID-ON-TXNSTS | POST /identity/txn/on-status | Response to async status check of previous identity transanctions using callback | ### Utilities Below are few utilities that community can open source: 1. Mobile / web app Toolkits to easily read a person's Verifibale Credentials to auto populate for social programs registration processes. 2. Toolkits to enable "offline" verification of beneficiary using VC data + local face match for proof of presence. 3. Online Auth/Kyc APIs using biometric based auth modalities using country specific Foundation ID implemenations. 4. Demographic deduplication utilities for scoial protection platforms where de-duplicated foundational ID is not be available/accessible. ### Integration Schematics # Credentialing ### Overview 1. Standardising credential issuance, search, verification, revokation and status check capabilities between G2P enabling DPGS/Products/Systems. 2. Country operational model shall decide the entity that manages one or more crendentialling systems. ### References 1. API specification link 2. Discussion [thread](https://github.com/G2P-Connect/.github/discussions) ### Interface List | Interface ID | End Point | Description | | -------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- | | CRED-ISSU | POST /credential/issue | Issue credential | | CRED-ON-ISSU | POST /credential/on-issue | Issuance info through callback | | CRED-SRCH | POST /credential/search | Search credential by credential id, issuer, beneficary id, etc., | | CRED-ON-SRCH | POST /credential/on-search | Credentail search results through call back | | CRED-STS | POST /credential/status | Credential status update request | | CRED-ON-STS | POST /credential/on-status | Credentail status update results through call back | | CRED-TXNSTS | POST /credential/txn/on-status | Perform async status check of previous credential requests using transaction\_id and/or reference\_id(s) | | CRED-ON-TXNSTS | POST /credential/txn/on-status | Response async status using callback | ### Integration Schematics # Registries ## Overview Success of any G2P program delivery depends on access to beneficiary information across various foundational and functional registries. {% code overflow="wrap" %} ``` An electronic registry is a structured & live identification system that gathers, saves, and maintains uniformed updated data or information on an entity, such as a patient, person, employee, student, or facility, and is constantly updated to serve as the entity's "Single Source of Truth" which is also verifiable. [ref: Sunbird-RC](https://docs.sunbirdrc.dev/learn/electronic-registries) ``` {% endcode %} The scope of G2P Connect Registry [interfaces](#interface-list) is to enable [federated](#federated-data-access) minimal read-only data access between platforms using [consented](#consented-data-sharing), [interoperable ](#interoperability)specifications. ## Federated Data Access G2P Connect [blueprint](/g2p-connect/solution-blueprint) recommends federated data access using electronic registries over centralised data stores using below design principles: 1. Social Protection Platforms MUST only have a **cache copy** of data 2. Social Protection Platforms (SPP) MUST fetch ONLY the **minimal or aggregated** data. for e.g., * Year of Birth or Age band instead of Date of Birth * Count by vehicle types instead of each vehicle info * Farmer land total acreage info instead of each identifiable land parcel info, etc., 3. Design/Implementation MUST allow minimal unified **read only** view of data as a cache. Implementations should **avoid** * Creating centralised data store(s) * Enabling capabilities to managing data attributes where legal mandate (i.e source of truth) is with another system(s) * Siloed data stores and with no capability to be in automated sync with source system(s) {% hint style="info" %} Above principles are also applicable to other domains like Agriculture, Health, Education, etc, where system to system data access is required for service delivery. G2P Connect recommends all systems involved in data exchange to enable below core features for interoperability using G2P connect [Registry APIs](#interface-list): 1. **search** - System in want of data shall **pull** from source system using search `query` 2. **subscribe** - System in want of data shall **register** to data subscription service(s) using `event(s`) and additional filters (optional) with the source system. 3. **notify** - Source system shall **push** data (on event or agreed frequency) to systems {% endhint %} ## Consented Data Sharing User consent is a core tenant of any digital process or digital infrastructure integrations. Registry data access API design accomdates the concept of the concept to enable access to data / services. Consent for data access is broadly classified in one of below operational modes with design aspects embedded into the core Registry API:
Implicit Consent Entity or system that is in need of user's data to provide services to the user shall obtain the consent directly from the user to initiate the data access process. For service requests initiated by beneficairy, Registry APIs allows to send the implicit **consent** in **search** query requests. *In Social Protection use case, this consent may be obtained during registration of the beneficiary into a social program and the consent may be very specific or broad enough to access required data from various systems, frequency or duration.* **Note:** For benficiary services initiated by entity/system through emergency and/or by legal process or intervention may use "**`authorise`**" attribute to access data.
Explicit Consent Entity or system that is in need of (or providing) user's data may obtain explicit (i.e informed) consent from a common trusted entity (e.g., consent manager). **In search flow**, entity/system in want of data shall obtain explicit consent. Entity/system providing access to data shall verify the consent shared in search request was indeed obtained from the common trusted entity (e.g., consent manager) before release the data as part of search query response. **In subscribe/notify flow**, entity/system providing data shall directly obtain explicit consent with the user and acts as a consent manager.
Implied Consent If user has access to verifiable credential(s) through that can be directly shared with entity/system providing the service user intends to avail then this is considered implied consent. If verifiable credential has the required data then no futher action is required to seek additional data, If verifiable credential is an auth token then entity/system providing data can use this as implied consent to release the data through search response.
### Consent Flows
Consent TypeData ConsumerData Provider
Implicit search: on-search:
Explicit search: on-search:
Implied User shares VC to directly avail serviceN/A
{% hint style="info" %} G2P Connect recommends a digitally signed machine readable consent artefact for trusted data exchange between entities. In the absence of this, the existing paper based, techno-legal approach may work for entities to trust each other to exchange data using Registry APIs. Use of *`"`**`consent`**`"`* attribute in APIs is recommend to implement this feature. {% endhint %} ## Authorised Data Sharing In emergency scenarios where local laws allow intervention access to critical data on time is critical to reach out to beneficiaries in need to provide immediate relief. In these scenarios, obtaining regular consent may not practically possible. Authorise attribute in search/subsribe requests enable data providers to share data to requesting entity. Authorise attribute may contain document reference that enable access to user data for specific purpose. Systems may audit this information for future references. ## Interoperability G2P Connect specifications is an attempt to enable interoperability both at Technology and Domain layers. **Technology** interoperability of the APIs are based on [design](/protocol/overview) principles to enable communcation/messaging protocol between systems in a [trusted](/protocol/security) manner. for e.g., * Transport layer agnostic support using REST, file exchange or message queues * Sync/Async modes * Reliable message delivery * End to end payload security, non-repudiable capabilities {% hint style="info" %} Auditability of data exchange requests is not in scope of these interfaces. As a best practice, registries that are providing data access services and systems consuming data should have good auditing mechanism built-in. G2P Connect does recommend to implement **consent** and authorised data artefacts to request and service {% endhint %} Additionally, G2P Connect Registry APIs are designed to accomodate various **Domain** process flows, data/message structures for data exchange that are country/department/use case context specific. ## References 1. API specifications - [html](https://g2p-connect.github.io/specs/release/html/registry_core_api_v1.0.0.html) | [yaml](https://g2p-connect.github.io/specs/release/yaml/registry_core_api_v1.0.0.yaml) 2. Discussion [thread](https://github.com/G2P-Connect/.github/discussions) *** ## Additional Information {% tabs %} {% tab title="Interface List" %} **`Async`** 1. /registry/subscribe - Subscribe for an event with registry 2. /registry/notify - Notify with data upon event or requested frequency 3. /registry/search - Search request using key identifiers or simple queries 4. /registry/on-search - Search results through callback 5. /registry/txn/status - Status check request for Async API using txn id or ref id 6. /registry/txn/on-status - Status check response through callback **`Sync`** 1. /registry/sync/search - Search request/response on same thread 2. /registry/sync/subscriptions - Fetch registered subscriptions 3. /registry/sync/unsubscribe - Unsubscribe to stop receiving data on notify API 4. /registry/sync/txn/status - Async APIs status check invoked synchronously {% endtab %} {% tab title="Registry Types" %} The Implementating systems are free to define registry type values using /[.well-known](https://en.wikipedia.org/wiki/Well-known_URI) folder as meta data for integration. {% hint style="info" %} Registry type is an optional value to indicate registry to query against and notify using event subscription. This is useful in case of system hosting multiple registries under an entity id! {% endhint %} {% @github-files/github-code-block url="" %} {% endtab %} {% tab title="Event Types" %} The Implementating systems are free to define event type values using /[.well-known](https://en.wikipedia.org/wiki/Well-known_URI) folder as meta data for integration. {% hint style="info" %} Event type is a mandatory value to indicate subscription service offered by a registry to notify data upon occurrence of an event. Optionally subscribers may opt for aggregated data push at requested frequency! Events can be defined at domain level registries. e.g., civil, farmer, student, disability, social, etc., {% endhint %} *** **Civil Registry** {% @github-files/github-code-block url="" %} #### Functional Registry {% @github-files/github-code-block url="" fullWidth="true" %} {% endtab %} {% tab title="Consent" %} {% @github-files/github-code-block url="" %} {% endtab %} {% tab title="Authorise" %} {% @github-files/github-code-block url="" %} {% endtab %} {% endtabs %} # Social Registry ## Overview In any social protection use case, access to beneficiary data from various department systems is key to determine beneficiary eligibility to a social assitance program/scheme. In social protection platform, criteria like below are common to determine an eligible beneficiary: 1. Be part of bottom x% of beneficiaries against set of social indicators; 2. Income at household level; 3. Assets - house, land, vehicle ownership, etc; 4. Expenditure - Electricity units consumed; last x months, avg of last x months, etc; 5. Not be part of other social programs - e.g Unemployment pension, Farmer Support Income, etc; One traditional approach is to create centralised database or data lake using one time pull/push of data sets from all relevant dept systems. This approach ends up creating a centralised data store where data quickly gets out of sync with source systems and social program administrators can't target the right beneficiaries. Complex scenarios (like below) forces implementations of social protection platforms to build **centralised data stores** and soon the data goes **out of sync** with source systems. 1. Criteria #1 (above) to determine bottom x% requires pooling all beneficiary data into one single data store 2. Criteria #5 (above) where proving beneficiary is **NOT** part of a registry G2P Connect recommends creating cache data complying to federated data access [principles](/protocol/interfaces/registries). # Beneficiary Management # Mapper Architecture ### Technology Architecture #### Version 1.0 ### 1. Introduction Governments around the world transfer funds to individuals for a variety of purposes, including cash benefits programs, subsidies, salaries, scholarships, etc., which are often programs managed by various departments at federal/national, state/province-level, or district levels. However, a nation can craft a reusable and minimalist digital public infrastructure component that can power multiple departments to run various G2P programs in an efficient and high-agency manner. This DPI building block can allow any government department to direct a payment to a financial account using just an identity number from an existing ID system, without recollecting financial information or re-engineering its own payments infrastructure. This architecture document highlights a recommended technology architecture design to enable any government to build its own financial address mapper. Any Government-to-Person (G2P) Payments program requires two key identifiers to complete the final stage of the benefit disbursement process - 1. Beneficiary Identifier 2. Target account information. The G2P Connect Blueprint, among other functions, enables abstraction of the target account where the beneficiary receives digital payments as a store-of-value. The store-of-value can be a bank account, mobile wallet, voucher, prepaid card, digital currency, etc. A Financial Address Mapper is a simple key/value lookup registry designed to manage beneficiary ID to store-of-value account information as Digital Public Infrastructure. Such a mapper is one building block of the G2P Connect Blueprint. ## 2. Design Principles Designing a Financial Address Mapper (FAM) should meet the core design principles outlined below. It is highly recommended that policy and technical architects take these principles into consideration when conceptualising and designing a Financial Address Mapper as a Digital Public Infrastructure.
### 2.1 Minimalism Financial Address Mapper shall require minimal information about beneficiaries. In an ideal scenario, only four fields (Beneficiary ID, Name, Store-of-Value Address, Linking Status) are required to manage this registry. Where possible, the store-of-value address need not contain full bank account/mobile money account details; it can simply direct to the financial institution holding the store-of-value account. FAM should avoid storing information about benefit schemes, scheme/beneficiary eligibility information, store-of-value account status, and similar data. Maintaining minimal data in the mapper shall keep external platform and system dependencies to a minimum. ### 2.2 Interoperability Building a Financial Address Mapper that is compliant with G2P Connect mapper open specifications allows authorised systems and services to access the mapper. The architecture enables interoperability with any bank, any wallet, any device, and any social protection program. It is up to the policy makers to control which ecosystem participants are allowed to support or implement Mapper features. For example, the linking API can be implemented by Social Protection System, or Store-of-Value Account Provider, or directly by the Mapper Hosting Entity. ### 2.3 Innovation Financial Address Mapper specifications use normalised addresses to represent ID and Financial Address. Normalised addressing enables innovation to easily accommodate new forms of foundational or functional IDs and Store-of-Value account types. Additionally, it allows ecosystem participants to innovate capabilities for easy access and updates to the mapper. ### 2.4 Asynchornous Financial Address Mapper architecture and design unbundle the capabilities to encourage multiple players in the ecosystem to participate. Financial account information resides in Banking Platforms while other ecosystem participants interact with aliases. This enables loosely coupled interaction between ecosystem participants to encourage market-driven engagement. Programs adopt mapper usage voluntarily based on readiness. This allows adoption to evolve asynchronously, incrementally rather than through a big bang approach. ### 2.5 Privacy & Security by Design Financial Address Mapper specifications recommend managing minimal information with optimal ignorance to protect security and privacy of the beneficiary. The design ensures that only the required participants will have access to account details for final debit/credit actions on store-of-value accounts. ### 2.6 Inclusivity & User Centric The Mapper should be designed to cover multiple types of store-of-value accounts that are inclusive across the population, including bank accounts, wallets, and mobile money accounts. Market innovations like purpose-limited vouchers, digital currencies etc., can easily be implemented using the G2P Connect proposed normative addressing. Normative addressing represents store-of-value account information using aliases like: ``` a. token:12345@mosip b. vid:12345@PhilID c. account:12345@gtbank d. account:12345@HDFC0000001.ifsc.npci e. joeuser@gtbank f. token:123456@sbi g. 12345@DCash ``` Beneficiaries are central to any Financial Address Mapper design and rollout. Beneficiaries should have easy access to one or more entities to link and manage life cycle events of the mapper. Ecosystem players shall innovate to allow self-service/assisted use and online/offline access capabilities to reach diverse categories of users. ### 2.7 +1 Change Financial Address Mapper is one of such components that can be easily unbundled from the existing platforms/systems/processes to build a new DPI component that opens up non-linear adoption with ease by embracing all aspects of DPI design principles. ### 2.8 Evolvability The Financial Address Mapper is not restricted to one instance in a country. G2P Connect Mapper specifications enable multiple mappers to co-exist and easily interoperate with each other through interoperable open specifications. Registries can evolve independently across account types, authentication modes, sectors, and regulatory or governance aspects of a country. ## 3. Mapper Ecosystem A typical Financial Address Mapper ecosystem players are: ### 3.1 Mapper Hosting Entity Entity managing mapper registry and ecosystem partners. It is recommended that a neutral agency host the mapper. Mapper Hosting Entity is responsible for: 1. Onboarding ecosystem partners and enabling access to mapper services through Open APIs, batch file interfaces, etc. 2. Design, Build, and Operate the Mapper registry. 3. Regulate and support other ecosystem partners through operational policies based on country-specific context. ### 3.2 Store of Value Provider Store-of-value providers that have direct relationships with beneficiaries to provide banking and financial services. Store-of-value providers perform the following activities: 1. Help interface beneficiaries to manage ID and store-of-value address with the entity hosting the mapper registry. 2. Authorise mapper linking requests by authenticating the right beneficiary. 3. Provide resolution of financial addresses to store-of-value account information for the final leg of digital payment credits using the underlying payment rails. 4. Transfer digital payments to store-of-value accounts.
### 3.3 Beneficiary A person approved by the social protection system to receive benefits from one or more social protection schemes. Beneficiaries receive the following benefits: 1. Manage store-of-value account information to receive all social benefits with one single entity and manage any life cycle changes only once. 2. Avoid having to share sensitive financial account information with multiple entities. ### 3.4 Social Protection System System delivering social protection to beneficiaries. Social protection systems enable the following capabilities: Help interface beneficiaries to manage ID to store-of-value address with the entity hosting the mapper registry. Create disbursement instructions to payment processing systems/rails to initiate benefit transfer using beneficiary ID.
## 4. Mapper Features G2P Connect specifications recommend the following features be available to enable seamless integration between G2P payments processing ecosystem participants: 1. Link: Links a store-of-value address with a beneficiary ID. Entity enabling beneficiaries to link must ensure authentication and obtain required consents. 2. UnLink: Performs a soft or hard delete of the mapper registry entry. 3. Resolve: Given a foundational or functional ID, helps find the store-of-value normative address. Country-specific implementations may allow resolution to financial entity codes or end store-of-value account identifiers. 4. Status Check: Systems integration service endpoint for applications to communicate and reconcile in an automated manner. This capability enhances reliability and improves user experience capabilities. 5. Update: Update financial and other linked information. The entity enabling beneficiaries to update information must ensure authentication and obtain all required consents. Below is an illustration of mapper implementation that enables beneficiaries to access funds or withdraw cash:
## 5. Recommended Best Practices 1. G2P Connect specification allows more than one mapper registry within a country. Having a registry within each ministry/agency or sector is perfectly fine as part of the initial rollout, and if there are enough synergies and trust built up, incremental consolidation will help both implementing agencies and beneficiaries. 2. Entities enabling linking (and life cycle management services) with the mapper registry MUST authenticate the owner of the account holder and the ID of the person being linked is indeed the same person. Specifications allow any existing authentication methods followed by the store-of-value service provider. 3. Obtaining consent is decentralised among the entities operating in the mapper registry ecosystem. This enables existing systems and business processes to adopt mapper registry as Digital Public Infrastructure. Migrating to Digital Consents shall help in population-scale operations with trust and enable automation. ## 6. Next Steps Countries may use the checklist below to start the DPI journey: 1. The Ministry/Department operating one or more social benefit program(s) may consider a single Mapper Registry as a Digital Public Infrastructure building block Department. This agency may own and operate the Mapper Registry. 2. Work with ecosystem participants to identify policies and operational guidelines to use the existing services digitally. ## 7. Additional References 1. Financial Address Mapper - [Architecture Overview](https://docs.google.com/presentation/d/e/2PACX-1vRm6L3Bn2wvOA39-E78Y8K3vUPVy_eH9IqAQkk9teNEKqxbM-fslXoh2scf5-_MXLTWpkqg1R17ejd0/pub?start=false\&loop=false\&delayms=3000) 2. Financial Address Mapper - Policy Overview 3. Financial Address Mapper - [Mapper API Specification](https://g2p-connect.github.io/specs/dist/g2p-mapper.html) # Mapper Specs ### Assumptions 1. Financial Address (FA) representred in normative form is pre-requisite for these api's to work 2. Payer/Payee FAs are to be obtianed by the respective financial entity that holds store of value accounts ### References 1. API specification [link](https://g2p-connect.github.io/specs/release/html/mapper_core_api_v1.0.0.html) 2. Discussion [thread](https://github.com/G2P-Connect/.github/discussions/16) ### Interface List | Interface ID | End Point | Description | | --------------- | -------------------------- | ----------------------------------------------------------------------------------- | | FAMAP-LNK | POST /mapper/link | Linking id / fa to mapper registry | | FAMAP-ON-LNK | POST /mapper/on-link | Linking response through callback end point | | FAMAP-UPDT | POST /mapper/update | Updating fa details against an id in mapper registry | | FAMAP-ON-UPDT | POST /mapper/on-update | Update response through callback end point | | FAMAP-ULNK | POST /mapper/unlink | remove id/fa link from mapper registry | | FAMAP-ON-ULNK | POST /mapper/on-unlink | Unlinking response through callback end point | | FAMAP-RSLV | POST /mapper/resolve | Resolve fa / beneficiary id to a store of value details | | FAMAP-ON-RSLV | POST /mapper/on-resolve | Resolve response through callback end point | | FAMAP-TXNSTS | POST /mapper/txn/status | Status check on any of the mapper actions using transaction\_id or reference\_id(s) | | FAMAP-ON-TXNSTS | POST /mapper/txn/on-status | Status check response through callback end point | ### Integration Schematics
# Eligibility Determination In order to make direct transfers governments need to identify the right beneficiaries for the various schemes - based on the scheme specific criteria. The data required for determining eligibility may include land holdings, electricity usage, vehicle ownership, financial transactions, age, gender, caste etc. These records currently reside in the respective departments but many ministries/departments are running initiatives to pull data into a centralised database. Over time systems have collated all the data into a centralised databases and are in a position to correlate these data to formulate a comprehensive profile of all the citizens. While the objective of such databases is to identify eligible beneficiaries, there are several challenges that may not aling with an ideal DPI design principles. 1. **Single Source of Truth** - The respective departments are the legal “registrars” of the respective attributes e.g. Vehicle records are owned by the Road Transport Department and so on. If data is being pushed into the central database, the ownership of ensuring the data is up to date should reside with the respective departments. The system must be designed in a manner to ensure that the most recent record is used to determine the eligibility criteria. 2. **Security** - Creating such a centralised database will make it a high risk asset and will require substantial investments in security to ensure adequate protection. Any compromise and unauthorised access to this database may cause irreverasable damage. 3. **Privacy** - Several questions around privacy arise which needs to be addressed e.g. will beneficiaries have visibility in the attributes that are being stored and used for eligibility determination, is there a process for them to raise correction requests, what mechanisms are put in place to ensure limit purpose of use of these databases, can beneficiaries opt out of such a database, etc. 4. **Anomaly Detection** - Since this database will be used for beneficiary eligibility, it will be a target for fraud. Mechanisms need to be put in place to detect anomalies e.g. population stability indexes must be computed and compared to ensure no large scale changes in the database are happening to enable inclusion in a specific scheme. To solve for above design principles, designers of these systems must consider federated services architecture rather than centralised databases. Instead of pulling all the data into a central database, it may be possible to implement a centralised “Beneficiary Eligibility” service which in turn calls respective departments “Beneficiary Eligibility” service that returns a “Yes/No” answer or minimal required information. So a scheme system queries the centralised beneficiary eligibility API by sending one or multiple records to it. The service then calls the respective department systems to check the beneficiary eligibility in their respective databases and revert with a result. The social program registry may **cache** this minimal information and additionally integrate with subscribe/notify api's to get notified on any source data changes at an agreed frequency to ensure latest correct data is available. This API driven approach shall ensure seamless integration with no manual intervention for each refresh cycle. Registration into social program scheme can allow beneficiary **grant/revoke consent** to access federated registries. Social program eligibility rules determine the source data sources to be linked to enable eligibiltiy determination. In addition to beneficiary consent, additional governance policies between systems to control attribute, aggregate level access to bring in trust. A federated architecture as illustrated below ensures the legal registrars of the data continue to hold respective the system of records while granting limited access to determine eligibility through standardised interfaces like [registry search api](/protocol/interfaces/registries).
# Program Management # Disbursement ### Overview 1. G2P Connect payment disbursement APIs intent is to enable standardisation between social protection and payment processing/rails systems integration. 2. Disburse and DisburseStatue are core entities to enable generation of payment instruction and reconcile processing status. ### References 1. API specification link 2. Disbursement feature relate [discussion thread](https://github.com/G2P-Connect/.github/discussions/15) ### Interface List | Interface ID | End Point | Description | | -------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | DISB-DISB | POST /disburse | Social protection platofrom initiating g2p disbursements | | DISB-ON-DISB | POST /on-disburse | Disbursement initiating systems receive disbursement status info through callback end points | | DISB-STS | POST /disburse/status | Request for disbursement status from (e.g) social protection, Treasury systems | | DISB-ON-STS | POST /disburse/on-status | Disbursement status to social protection, Treasury systems. | | DISB-ON-TXNSTS | POST /disburse/txn/status | Disbursement status to social protection, Treasury systems. | | DISB-ON-TXNSTS | POST /disburse/txn/on-status | Disbursement status to social protection, Treasury systems. | | DISB-STS-TXNID | GET /disburse/status/{transaction\_id} /{summary\_only} | Disbursement status to social protection, Treasury systems | | DISB-STS-REFID | GET /disburse/status/{reference\_id}] | Disbursement status to social protection, Treasury systems | ### Integration Schematics
# Security # Authorization ### Overview 1. The scope of these end points is to standardise issuance of access tokens using existing OAuth2/OIDC standards.\\ 2. Helps standardise end point access across g2p complaint api stack using x-access-token that is compliant with JWT specs.\\ 3. DPGs & COTS products may also provide similar authz api end points with G2P Connect documented scopes as part of each country specific implementation (if any).\\ 4. Additional security like IP white listing, private networks, etc are outside the scope of G2P Connect standards. Each country shall decide required operational models.\\ #### References 1. API specification [link](https://g2p-connect.github.io/specs/release/html/auth_core_api_v1.0.0.html) 2. Discussion [thread](https://github.com/G2P-Connect/.github/discussions) ### Interface List | Interface ID | End Point | Description | | ------------ | -------------------- | ------------------------------------------------------ | | AUTHZ-TOKN | /oauth2/client/token | Provide access token to registered senders & receivers | ### Integration Schematics # Singature Validation # References 1. GitHub Specification [Source](https://github.com/G2P-Connect/specs/tree/draft/src) 2. G2P Connect [APIs](https://g2p-connect.github.io/specs/release/index.html) 3. G2P Connect [Discussions](https://github.com/G2P-Connect/.github/discussions/categories/ideas-enhancements) 4. G2P Connect [Website](https://g2pconnect.global) # Acknowledgments Thanks to below organization/individuals for their contributions and influencing the G2P Connect standards. 1. G2P community [members](https://g2pconnect.global/partners.html) # Licensing Content of this site is licensed under CC BY-SA 4.0 by CDPI