{"id":28577552,"url":"https://github.com/mastercard/web-merchant-api-sdk","last_synced_at":"2025-06-11T00:38:55.523Z","repository":{"id":51053391,"uuid":"292520811","full_name":"Mastercard/web-merchant-api-sdk","owner":"Mastercard","description":null,"archived":false,"fork":false,"pushed_at":"2021-05-25T12:40:29.000Z","size":87,"stargazers_count":2,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-16T10:43:25.937Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mastercard.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-03T09:10:15.000Z","updated_at":"2024-04-16T10:43:25.938Z","dependencies_parsed_at":"2022-08-24T14:40:01.445Z","dependency_job_id":null,"html_url":"https://github.com/Mastercard/web-merchant-api-sdk","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fweb-merchant-api-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fweb-merchant-api-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fweb-merchant-api-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fweb-merchant-api-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mastercard","download_url":"https://codeload.github.com/Mastercard/web-merchant-api-sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fweb-merchant-api-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259177333,"owners_count":22817349,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-11T00:38:13.765Z","updated_at":"2025-06-11T00:38:55.506Z","avatar_url":"https://github.com/Mastercard.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Web Merchant API \n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n## Overview\nThe Web Merchant API SDK is written in JavaScript. It can be included on any Website by following a few simple steps The Web Merchant API enables distributors to get details of banks and to invoke the bank apps using the SDK. The SDK is provided by Zapp and is ready to implement. \n### Audience\nSDK intended to be used by external Participants to support the implementation and subsequent use of the Web Merchant API.\n\n## Integration and Implementation of the Web Merchant API\n\n## Contents\n- [Functional overview](#functional-overview)\n  - [Introduction](#functional-overview)\n  - [Flow Diagram](#flow-diagram)\n  - [User Journey](#user-journey)\n  - [Certified Browsers and Devices](#certified-browsers-and-devices)\n  - [Sequence Diagram](#sequence-diagram)\n- [Technical overview](#technical-overview)\n  - [Introduction](#technical-overview)\n  - [Pre- requisites](#pre--requisites)\n  - [Availability of Web Merchant API SDK](#availability-of-web-merchant-api-sdk)\n  - [Folder Components](#folder-components)\n  - [Guidelines to Integrate the Web Merchant API](#guidelines-to-integrate-the-web-merchant-api)\n    - [General requirements](#general-requirements)\n    - [Integration Steps](#integration-steps)\n  - [Web Merchant API Interface](#web-merchant-api-interface)\n    - [Implementation Steps](#implementation-steps)\n- [Appendices](#appendices)\n  - [Template file](#template-file)\n  - [Error Codes](#error-codes)\n- [Troubleshooting](#troubleshooting)\n \n## Functional overview\n### Introduction\nThe Web Merchant API is a web library that enables a merchant/distributor to enable payments through a consumer selected CFI on a single device.\nThe Web Merchant API enables the merchant to get information about the CFIs supported by Mastercard for PBA-RFP. This CFI information can be used by the merchant to display supported CFIs on their website during an invoice presentment. A consumer can see the available banks and select and launch a CFI he wants to pay with. \n\n### Flow Diagram\n\u003cimg src=\"https://user-images.githubusercontent.com/51792552/106197173-467f1400-61aa-11eb-8dc9-a35004949540.png\" width=\"552\" height=\"568\"/\u003e\n\n##### Figure 1: Flow diagram of user journey \n\n### User Journey\n\n\u003cimg src=\"https://user-images.githubusercontent.com/51792552/106196037-db810d80-61a8-11eb-91ef-06c44804ebb5.png\" width=\"1050\" height=\"400\"/\u003e\n\n##### Figure 2: User journey \n\n##### User journey steps:\n 1. User on merchant website selects a CFI during an invoice presentment.\n 2. CFI app is launched with Account details. User confirms the payment on the CFI App.\n 3. User is presented the Order confirmation on the CFI App.\n 4. User is redirected back to the success page on Merchant website on successful payment.\n\n### Certified Browsers and Devices\nZapp has certified the Web Merchant API SDK to work with the following browsers and respective devices:\n\n|Mobile (iOS)\t| Operating System/ Browser | OS Version | Comments |\n|---------------|---------------------------| -----------| -------- |\n| iPhone X |\tChrome, Safari, Firefox|13.6.1\t|           |\n|iPhone 6 |\tSafari and Chrome |\t12.4\t|           |\n|iPhone 6S Plus| Safari and Chrome |\t13.3\t|           |\n\n##### Table 1: \tCertified Browsers and devices\n\n### Sequence Diagram\n\n![sequence](https://user-images.githubusercontent.com/51792552/106197177-4717aa80-61aa-11eb-823b-09550b5d9802.png)\n\n##### Figure 3: \tSequence diagram \n\n## Technical overview\n### Introduction\nThis chapter provides instructions on the implementation of the Web Merchant API SDK.\n\n### Pre- requisites\nPlease ensure that the Mastercard process of distributor/merchant on boarding has been completed.\n\n### Availability of Web Merchant API SDK\nAfter completing the on boarding with Mastercard, download the Web Merchant API SDK from the below location.\n [Placeholder for github location ]\n \n|File Name / Version |\tHosted On |  Version   | Download Location |\n|--------------------|------------| -----------| ----------------- |\n|Web_merchant_api.zip |\t\t  | 1.0.0      |                   |\n\n##### Table 2: \tWeb Merchant API SDK Library download location\n\n### Folder Components\nThe Web Merchant API SDK is a JavaScript based product. It consists of a JavaScript file and a template file in a folder. \nThe overall folder structure is represented in Figure below and contains:\n1. A versioned **zapp-merchant-api-artefact-1.0.0.js** file.\n2. A **zapp-merchant-api-externalJs.template** file which contains sample code explaining the use of the library and how to invoke the APIs.\n3. A License for the SDK\n4. A CONTRIBUTING.md file which contains a description for how developers can contribute the project\n5. A README.md file which contains a brief description about the SDK.\n6. A CHANGELOG.md file which contains a curated, chronologically ordered list of notable changes for each version of a project.\n\n![image](https://user-images.githubusercontent.com/51792552/106197084-251e2800-61aa-11eb-9333-fe6690447349.png)\n\n##### Figure 4:\tWeb Merchant API SDK folder structure \n\n### Guidelines to Integrate the Web Merchant API \n#### General requirements\nThe following table shows the general requirements to setup the Web Merchant API SDK.\n\n|Component |                                    \tVersion                   |\n|----------|----------------------------------------------------------------------|\n| JQuery   |\t3.5.1                                                             |\n\n##### Table 3: \tWeb Merchant API SDK – Setup requirements\n\nJQuery is used by the Web Merchant API SDK to perform various operations. It should be the first script to be imported in the project. JQuery can be included by printing the following HTML script tag in the parent HTML page in the header section:\n\n```javascript\n\u003chead\u003e\n…\n\u003cscript src=\"https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js\"\u003e\u003c/script\u003e\n…\n\u003c/head\u003e\n```\n\nThis will import the JQuery plugins in to the project.\n\n**Note:** This version of JQuery is the current certified version for Web Merchant API functioning on the supported browsers and devices. Support for the latest version of JQuery is on the Web Merchant API Product Roadmap and will be considered for future releases of this SDK.\n \n#### Integration Steps\nFollow the below mentioned steps to include the Web Merchant API in the Merchant website.\n1. Extract the Web_merchant_api.zip and add the **zapp-merchant-api-artefact-1.0.0.js** in the project.\n2. Import the JavaScript library zapp-merchant-api-artefact-1.0.0.js in the parent page where the bank list needs to be displayed by adding the script tag in the html page.\n\n##### Example:\n\n```javascript\n\u003chtml\u003e\n    \u003chead\u003e\n    \t\u003cscript src=\"../zapp_merchant_api_assets/zapp-merchant-api-artefact-1.0.0.js\"\u003e\u003c/script\u003e\n    \u003c/head\u003e\n\u003c/html\u003e\n```\n \n### Web Merchant API Interface\nThe Web Merchant API SDK interface exposes the following functions to be integration by the merchant. \n1. **getCfiDetails**: This function retrieves the list of supported CFIs for PBA-RFP by Mastercard. This list contains the names, the logo and the unique id assigned to the CFI by Zapp. \n2. **invokeApp**: This function is used to invoke the consumer selected banking app using the unique universal link for the CFI.\n\n#### Implementation Steps \nUse the following steps to invoke the SDK’s API in the Merchant website.\n\n- Invoke the **zappMerchantApi.getCfiDetails** function in the merchant website specific external js file used on the page where bank list is to be displayed. This function returns a promise with a value true when resolved, merchant can then use the **zappMerchantApi.cfiDetails** object to display the bank list with additional bank information like name and logo on their page. This function must be invoked as soon as the page's Document Object Model (DOM) becomes ready.\n\n##### Example:\n\n```javascript\n$(document).ready(function() {\n\t\n\tvar merchantFunctionToInvokeGetCFIDEtailsApi= function () {\n        \tzappMerchantApi.getCfiDetails.then(function(result) {\n\n\t/* Promise is resolved, use the zappMerchantApi objects to display the bank details. \n\t   Two zappMerchantApi objects are:\n\n\t1. zappMerchantApi.cfiDetails – A list of banks with the following details.\n\t\ti. cfiLogo: \"https://cdn/..../bankName-bank.png\"\n\t\tii. cfiName: \"Bank name\"\n\t\tiii. cfiUniqueId: \"Bank Unique Id\"\n \n\t2. zappMerchantApi.cfiCount – Total number of banks */\n\t\n\t})\n        .catch(function (error) {\n\t\t// Merchant specific code\n        });\n};\n```\n\nSample **zappMerchantApi.cfiDetails** object which contains information of four Banks:\n\n```javascript\n0: {cfiUniqueId: \"273841\", cfiName: \"bankName1\", cfiLogo: \"https://cdn/..../bankName1-bank.png\"}\n1: {cfiUniqueId: \"902738\", cfiName: \"bankName2\", cfiLogo: \"https://cdn/..../bankName2-bank.png\"}\n2: {cfiUniqueId: \"829456\", cfiName: \"bankName3\", cfiLogo: \"https://cdn/..../bankName3-bank.png\"}\n3: {cfiUniqueId: \"126488\", cfiName: \"bankName4\", cfiLogo: \"https://cdn/..../bankName4-bank.png\"}\n```\n\n- Invoke the zappMerchantApi.invokeApp function to open the user selected Bank App. This API must be called when consumer selects one of the banks from the list displayed by the Merchant on the page. This API requires three parameters.\n  - CFI Unique Id – This is the cfiUniqueId of the selected bank. This value is Zapp assigned unique id available in zappMerchantApi.cfiDetails object.\n  - AptrId – It is returned by Zapp in response to SubmitRFP API triggered by the Merchant on selection of a bank by the consumer.\n  - Product Type – The value of this parameter must be PBA-RFP. This is not case sensitive.\n\n##### Example:\n\n```javascript\nfunction paymentRequestToMechantServer(clickedBtn) {\n\n// Merchant’s logic to invoke the Submit RFP API. After successful response AptrId is received by merchant.\n// Use the same as one of the parameter to invoke the zappMerchantApi.invokeApp function. \n\n\tzappMerchantApi.invokeApp(cfiUniqueId, aptrId, 'PBA-RFP'); \n\t\t\t\t\n}\n```\n\n- Register a listener to capture the error log event returned from the SDK. The event returns an error log data which contains error Id, error description and error time stamp.  Please ensure that the event name is used exactly the way it is mentioned below. Refer the section Error Codes for more details. \n\n##### Example:\n\n```javascript\nfunction listener(event) {\n\tvar evData =event.data;\n\tif(evData.eventType == \"zappMerchantApiError\" ){\n\t\tconsole.log(evData.data)\n\t}\t\n}\n```\n\n## Appendices\n### Template file\nThe **zapp-merchant-api-externalJs.template** file contains the sample code to demonstrate the use of the Web Merchant API SDK.  This code also depicts the implementation of the custom method to post payment request to the Merchant Server. This file resides in the Web Merchant API SDK folder along with the zapp-merchant-api-artefact-1.0.0.js file.\n**Note**\tAny data elements and comments in Italic are a Merchant specific data element which must be provided by the Merchant.\n**Assumption**\tThis is the JS file used on the Merchant’s website.\n\n\n##### Sample code:\n\n```javascript\t\n$(document).ready(function() {\n\t\t\n\t\tvar invokeSbiCfiApi= function () {\n\t\t// Web Merchant API function to get the bank details. \n\t\tzappMerchantApi.getCfiDetails.then(function(result) {\n            /*  Promise is resolved, use the zappMerchantApi objects to display the bank details.\n\t    \tTwo zappMerchantApi objects are:\n\n\t\t1. zappMerchantApi.cfiDetails – This object contains the list of banks with the following details.\n\t\t   i.\t cfiLogo: \"https://cdn/..../bankName-bank.png\"\n\t\t  ii.\t cfiName: \"Bank name\"\n\t\t  iii. cfiUniqueId: \"Bank Unique Id\"\n\t\t\t\t \n\t\t2. zappMerchantApi.cfiCount – It contains the number of banks present in the CDN file */\n\n\t\tmerchantFunctionToRenderBankLogos(); //\n            \n        })\n        .catch(function (error) {\n            //Merchant specific code\n        });\n\t};\n\tmerchantFunctionToRenderBankLogos();\n});\n\n// Merchant specific implementation. \nmerchantFunctionToRenderBankLogos = function(){\n\tfor(i=0;i\u003czappMerchantApi.cfiCount;i++)\n\t{\n\t$(\"#merchantBankListContainer\").append('\u003cli\u003e\u003cimg src=\"'+\n\t\tzappMerchantApi.cfiDetails[i].cfiLogo+'\" alt=\"'+zappMerchantApi.cfiDetails[i].cfiName+\n\t\t'\"\u003e\u003cspan\u003e\u003cp\u003e'+zappMerchantApi.cfiDetails[i].cfiName+\n\t\t'\u003c/p\u003e \u003cspan\u003eBank Account\u003c/span\u003e\u003c/span\u003e\u003ca id=\"'+zappMerchantApi.cfiDetails[i].cfiUniqueId+\n\t\t'\" href=\"#\" onclick=submitRFP('+zappMerchantApi.cfiDetails[i].cfiUniqueId+')\u003eSelect\u003c/a\u003e\u003c/li\u003e');\t\t\n\t}\n}; \n\nfunction merchantFunctionToInvokeGetCFIDEtailsApi(bankId) {\n\tvar cfiID = bankId.id; // This must contain the CFI Unique id of the selected bank\n\tvar response = '';\n\tvar merchantRequestForPayPostData = {\n\t\t// Merchant Request for Payment Post Data \n\t};\n\t\n\tjQuery.ajax({\n\turl : merchantRequestForPayPostOrder, \", //The merchant URL to post the Request for Payment\n\tdataType : \"json\",\n\tcontentType : \"application/json; charset=UTF-8\",\n\ttype : \"put\",\n\tasync: false, \t// Keep it as it is\n\tdata : JSON.stringify(merchantRequestForPayPostData),\n\tcrossDomain : true,\n\tsuccess : function(merchantRequestForPaymentResponseObject) {\n\t\tajaxFlag = true; // flag to indicate that ajax call is completed successfully\n\t\t response = {\n\t\t\tsuccess : true,\n\t\t\taptrId : merchantRequestForPaymentResponseObject.aptrId,\n\t\t\t\t//other details\n\t\t\t};\t\t\t\t\n\t\t},\n\t\terror : function(merchantRequestForPaymentResponseObject) {\n\t\t\t// Merchant specific code to handle error\n\t\t}\n\t});\n\t\n\t// If the ajaxFlag is true then zappMerchantApi.invokeApp function is invoked.\n\t\n\tif (ajaxFlag == true){\n\t\t//Web Merchant API function to invoke Bank APP. These three parameters are required for opening the bank app\n\t\tzappMerchantApi.invokeApp(cfiID, response.aptrId, 'PBA-RFP');  \n\t }\n}\n\nfunction listener(event) {\n\tvar evData =event.data;\n\t// Check for zappMerchantApiError event for the Error details\n\t// event.data contains the Error object with the following information\n\t// \t\terrorDesc\n\t//\t\terrorId\n\t//\t\terrorTimestamp\n\t\n\tif(evData.eventType == \"zappMerchantApiError\" ){\n\t\tconsole.log(evData.data); // Merchant specific code to handle the errors\n\t}\t\n}\n\nif(window.addEventListener){\n\t addEventListener(\"message\", listener, false)\n} else {\n\t attachEvent(\"onmessage\", listener)\n} \n```\n\n\n### Error Codes\nThe Web Merchant API SDK captures the error while executing the **zappMerchantApi.getCfiDetails** and **zappMerchantApi.invokeApp** functions. The SDK returns and event with the error Id, error description and a timestamp. Below mentioned table describes all the Error Codes defined in SDK.\n##### Sample error object:\n\n```javascript\nzappMerchantApiError:{\n“errorDesc”: \"Error Description\",\n“errorId”: \"Sxxx\",\n“errorTimestamp”: \"Mon, 24 Aug YYYY 00:09:02 GMT\" }\n```\n\nError codes|Error description|Cause of the error\n-----------|-----------------|------------------\nS1001|CFI Id is undefined|When **zappMerchantApi.invokeApp** function is invoked without CFI Id.\u003cbr\u003e\u003cbr\u003eExample: **zappMerchantApi.invokeApp(undefined,aptrId,’PBA-RFP’)**|\nS1002|AptrId is undefined|When **zappMerchantApi.invokeApp** function is invoked without AptrId.\u003cbr\u003e\u003cbr\u003eExample: **zappMerchantApi.invokeApp(cfiId,undefined,’PBA-RFP’)**\nS1003|Product Type is undefined|When **zappMerchantApi.invokeApp** function is invoked without product type.\u003cbr\u003e\u003cbr\u003eExample: **zappMerchantApi.invokeApp(cfiId,aptrId,undefined)**\nS1004|CFI Id is null or empty|When **zappMerchantApi.invokeApp** function is invoked with empty CFI Id or with null value.\u003cbr\u003e\u003cbr\u003eExample: **zappMerchantApi.invokeApp(‘’,aptrId,’PBA-RFP’)**\u003cbr\u003eOr\u003cbr\u003e**zappMerchantApi.invokeApp(null,aptrId,’PBA-RFP’)**\nS1005|AptrId is null or empty|When **zappMerchantApi.invokeApp** function is invoked with empty Aptr Id or with null value.\u003cbr\u003e\u003cbr\u003eExample: **zappMerchantApi.invokeApp(cfiId,’’,’PBA-RFP’)**\u003cbr\u003eOr\u003cbr\u003e**zappMerchantApi.invokeApp(cfiId,null,’PBA-RFP’)**\nS1006|Product Tpye is null or empty|When **zappMerchantApi.invokeApp** function is invoked with empty productType or with null value.\u003cbr\u003e\u003cbr\u003eExample: **zappMerchantApi.invokeApp(cfiId, aptrId,’’)**\u003cbr\u003eOr\u003cbr\u003e**zappMerchantApi.invokeApp(cfiId, aptrId,null)**\nS1007|No data present for CFI Id|When **zappMerchantApi.invokeApp** function is invoked with empty productType or with null value.\nS9997|Unknown error has occured|When an unknown error occurs while invoking the **zappMerchantApi.invokeApp** function\nS9998|An error has occurred while reading the JSON file.\u003cbr\u003e Error Type: errTyp . Error Text: errTxt|When **zappMerchantApi.getCfiDetails** function is invoked and an error occurs. \nS9999|An unknown error has occurred|When an unknown error occurs while invoking the **zappMerchantApi.getCfiDetails** function\n\n##### Table 4: \tWeb Merchant API SDK – Error Codes\n---\n## Troubleshooting\nThis section covers the different troubleshooting scenarios and the behaviour of the Web Merchant API. \n1. For the SDK to work as expected the default browser settings should allow pop ups to open on the mobile device.\n2. If merchant is using jquery ajax call to invoke Submit RFP then merchant must wait for the ajax call to complete to invoke the **zappMerchantApi.invokeApp** function of the SDK. Alternatively merchant can use the async: false parameter when making an ajax call. Refer the template file in the SDK for an example.\n3. The Web Merchant API SDK opens a new tab to redirect to the universal link provided by the bank. If the bank app is not installed on the consumer’s device then the page displayed on the new opened tab is handled by the bank. \n\n## Contributing\nFor major changes, please open an issue first to discuss what you would like to change.\n\nPlease make sure to update tests as appropriate.\n\n## License \u003ca name=\"license\"\u003e\u003c/a\u003e\nCopyright 2020 Mastercard\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with\nthe License. You may obtain a copy of the License at:\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on\nan \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the\nspecific language governing permissions and limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Fweb-merchant-api-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmastercard%2Fweb-merchant-api-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Fweb-merchant-api-sdk/lists"}