GOOGLE CONFIDENTIAL & PROPRIETARY 

Microapps Developer Guide 

Introduction 

Overview 

Building 
Client 
Server 

Configuring 
For Identity API 
For Server APIs 

Testing 
Overview 
Web Simulator 
APK 

API Reference 
Payments API 
Request 
Response 
Verifying The Signed Response 
Identity API 
Response 
Decoding and Verification 
Error codes 
Phone number API 
Sharing API 
Location API 
Response 
Orders API 
createOrder 
getOrder 
updateOrder 
Messages API 
Deep-linking 
Performance Optimization 
Initial page load 
Page transitions 
Service Workers 

 
v0.2 India EAP 
1 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

Feature policies 
 

Introduction 
The Microapps platform lets developers integrate rich and engaging experiences into the Google Pay app. 
Users are able to discover these experiences from the Google Pay app, or through a link shared outside 
the app, and engage with them without the need to download or install anything additional. Making a 
purchase in a Microapp is as quick and easy as tapping a single button. 
 
Here is an overview of the different parts of a Microapps integration from a user perspective: 
 
● Discovery - A ​ merchant can be discovered from the Google Pay app, or through a link shared by 
the merchant or their friends. 
● Conversation​ - there is a conversation (chat) for each merchant in the app, which contains the 
transaction history between the merchant and the user 
● Storefront​ - a bottom sheet called the storefront shows up in the conversation UI for merchants 
with a microapp, offering one or multiple entry points into their microapp 
● Custom experience​ - from the storefront, or from a link, users enter the actual microapp; this is a 
custom experience completely defined by the developer / merchant 
● Features/APIs​ - the microapp integrates with APIs for actions such as payments, identity, or 
location 
● Orders​ - for any completed transaction, microapps write information about the purchased items 
and status back to the chat to allow the user to view and track their purchase 

Overview 
A microapp is essentially a web app that can be built using any framework (e.g. Angular or React), and be 
hosted on any platform (e.g. GCP or Firebase). A set of configurations control how the microapp shows 
up in the Google Pay app (incl. the name and logo of the microapp and the entry points from the 
storefront), and a set of client and server APIs are offered for a microapp to integrate with the Google Pay 
experience (incl. triggering a payment and writing back order details). The web app itself is hosted directly 
by the developer, similar to a mobile website. 
 
The building blocks of the Microapps platform from a developer's perspective are: 
 
● HTML/CSS/JS​ - standard web technology to build a rich and engaging experience for users that 
lives right inside the Google Pay app 
● Client and server APIs​ - a set of APIs to call directly from microapp's web page JS code, or the 
microapps server to request a payment, write back order details, or learn the user's location 
● Hosting​ - a place to host the microapp web app; this could be a developer's existing web server, 
or a new​ Cloud Functions for Firebase​ instance 
 

 
v0.2 India EAP 
2 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

 
 
 
A typical life of a microapp transaction would look like this: 
 

Building 
This section covers topics on building a microapp. 

Client 
Include the following script in any web page that is part of your microapp: 

 
v0.2 India EAP 
3 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

 
<script type="text/javascript"
src="https://microapps.google.com/apis/v1alpha/microapps.js" />
 
This will make your web page a Microapp page, and give you access to the Microapps client APIs. 
 
Here's a few things to note about building web pages for your microapp: 
 
● All web pages making up a microapp must be served via HTTPS only 
● The web pages making up a microapp must allow iframing
● Navigation to web pages hosted on domains other than the one of your microapp is not allowed 
and will be prevented by the runtime 
 
Recommendations: 
 
● Use HTML5 ​Web Storage APIs​ to cache assets, store state and achieve a fast, resumable 
experience when users return to the microapp 
● Include the following header when serving your web pages: "​X-Frame-Options: allow-from
https://microapps.google.com/​" 
● Refer to ​Performance Optimizations​ for more recommendations on how to build a fast microapp 

Server 
The server-to-server APIs for orders and messages need to be enabled for your Google Cloud project, and 
require authentication with OAuth 2.0 and a service account for all calls. Follow these guides, if you don't 
already have a Cloud project and/or service account to use: 
 
● Creating and Managing Projects 
● Creating and managing service accounts 
● Enabling and Disabling APIs 
 
Refer to the O
​ rders API​ and M
​ essages API​ sections on how to use these APIs from the server. 
 
Note: the user agent of the requests sent by the Microapp viewer is [​ GPay-Microapps/<google pay
version>]​. 
 

Configuring 
This section covers topics on configuring a microapp for deployment in the Google Pay app. 
 
1) All microapps in Google Pay are linked to a merchant, and so the first step in setting up a microapp is 
to register a merchant, if there isn't one already, via the ​Google Pay for Business console 
 
2) Provide the following information to Google: 
 
v0.2 India EAP 
4 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

 
Core data (this defines a microapp) 

Name  Name of the microapp 

Icon PNG  Icon of the microapp (48x48) 

Base URL  Home page / app shell URL 

Merchant ID  For India, this is the merchant id from Google Pay for business console, after the 
agent approves your business, your chat head will start showing up in Google Pay 
India search. The VPA provided for onboarding should be used for requesting 
payment.  

Project number  Project number of the Google Cloud project (required only if the microapp will be 
using sign-in functionality) 

Test account  Google account or group that has access to microapp before public release. 

Listing data (to appear in listings, primer, etc.) 

Image PNGs  One or more screenshots illustrating the microapp. 

 
Aspect ratio of 1:2, recommended measurement: 480 x 960 pixels. 

Descriptions  Descriptions to go with the screenshots above. 

 
Language required: EN 
 
Additional languages: BN (Bengali), GU (Gujarati), HI (Hindi), KN (Kannada), MR 
(Marathi), TA (Tamil), TE (Telugu) 

ToS URL  URL to the terms of service for the microapp (hosted by the developer) 

Main entry points in storefront* 

Title  Title for the microapp main entry point 

Additional entry points in storefront* (zero or multiple) 

Label  Label for the microapp entry point.  

Icon PNG  Icon for the microapp entry point. (A set of icons will be provided for selection) 
*Storefront is the bottom sheet in the Conversation UI, which serves as the entrypoint into the microapp 

For Identity API 

If the microapp will use the identity APIs, a Google Cloud project needs to be set up via the G
​ oogle Cloud 
console​, and OAuth 2.0 needs to be set up (see g​ uide​), if that hasn't been done already 
 
v0.2 India EAP 
5 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

For Server APIs 

If the microapp will be calling the Orders API or Messages API from the server: 
 
1) a service account will need to be created (see ​guide​), if there isn't already one 
 
2) a Google Cloud Platform (GCP) project will need to be created (see g ​ uide​), if there isn’t already one 
 
3) in your GCP project, setup a service account dedicated to the usage of Microapps API 
● please only use one service account per microapp and send the service account email to your 
Google representative, for authorization 
● ask your Google representative to register the cloud project and whitelist your project developer 
email account. 
● you can now enable the Microapps API (see details h ​ ere​) Download the service account JSON file 
into your local code path for authenticated API access from your server. 
 
4) connect your service account to the Microapps API endpoint by setting up OAuth2.0  
 
The Microapps API scope for OAuth2.0 is 
https://www.googleapis.com/auth/microapps.orders 
 
Example 
import httplib2

from oauth2client.service_account import ServiceAccountCredentials

_SERVICE_ACCOUNT_JSON = 'service_account.json'

_API_SCOPES = [
'​https://www.googleapis.com/auth/microapps.orders​']

# an example api url of create order

_API_URL = '​https://microapps.googleapis.com/v1alpha/orders/'

# Get service account credentials.

credentials = ServiceAccountCredentials.from_json_keyfile_name(
_SERVICE_ACCOUNT_JSON, _API_SCOPES)

# Provides an authed http object.

http_client = credentials.authorize(httplib2.Http())

# Json payload, here is just a place holder to showcase

# the http connection only. See API reference of how to fill

 
v0.2 India EAP 
6 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

# request json payload.

body_value = '{}'

# HTTP POST request, should return 200 OK HTTP status upon success.
# The 'header' will be header of the response in json format, and
#'content' will be the payload of the response in byte[]
header, content = http_client.request(_API_URL, method='POST',
body=body_value)

If you have used the ​GCP python client library​ and want to replace the above ​http.request 
connection by gRPC client connection, Microapps API does not support it yet. 

Testing 
This section covers topics on testing a microapp / a new version of a microapp before launching it to 
users. 

Overview 
There are different ways of testing a microapp, depending on the lifecycle of development: 
 
● during development 
○ use the browser-based simulator (see below) 
● during functional testing: use the app-based debug mode 
○ Obtain the partner build of the Google Pay app from Google 
○ Login with the test account that provided in the app registration step 
○ Search for the microapp / merchant by name in the app 

Web Simulator 
The web simulator is a simple tool that can display a microapp in a web browser and mock API calls by 
prompting the user to enter the desired response to the microapp manually. 
 
The web simulator can be started from the following URL, by passing the microapp's URL endpoint as the 
"appUrl" parameter: 
 
https://microapps.google.com/simulator?appUrl=https://example.net/microapp.html

 
v0.2 India EAP 
7 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

APK 
You can also use the provided APK to load your Microapp. For merchants who already are on the GPay 
app, please talk to us to make sure that we’ve setup the blacklist properly so that only your development 
team can see the Microapp.  
You can load the Microapp using the following adb command: 
adb shell am start -a android.intent.action.VIEW -d
https://microapps.google.com/[your​ microapp id] 
 
for example: 
adb shell am start -a android.intent.action.VIEW -d
https://microapps.google.com/​com.google.my.microapp 
 

API Reference 
This section is a detailed reference of the features and APIs available with the Microapps platform. 

Payments API 
To request a payment from the user, the microapp can call the following JS method: 
 
requestPayment(request).then(...)

Request 
 
Example 
{
​"apiVersion"​:​2​,
​"apiVersionMinor"​:​0​,
​"allowedPaymentMethods"​: [{
​"type"​:​"UPI"​,
​"parameters"​: {
​"payeeVpa"​:​"merchant@psp"​,
​"payeeName"​:" ​ Merchant Name"​,
​"mcc"​:​"0000"​,
​"transactionReferenceId":"785315c6-d536-4737-a31a-fc907e3d4f9b"​,
​"referenceUrl"​:​"h
​ ttps://www.example.net/transaction/12345​"​,
​"transactionId":"AXI123"

 
v0.2 India EAP 
8 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

},
​"tokenizationSpecification"​: {
​"type"​: ​"DIRECT"
}
}],
​"transactionInfo"​: {
​"countryCode"​: ​"IN"​,
​"totalPriceStatus"​: ​"FINAL"​,
​"totalPrice"​: ​"13.00"​,
​"currencyCode"​: ​"INR"​,
​"transactionNote"​: ​"Extra note about this transaction"​,
}
}
 

Property  Type  Description  Required/Optional 

apiVersion  Int  Must be set to 2 to support the current API  Required 

implementation 

apiVersionMinor  Int  Must be set to 0 for the current  Required 

implementation (it will be incremented on 
every backwards compatible change to the 
API) 
 
allowedPaymentMethods
 
Property  Type  Description  Required/Optiona
l 

type  String  Currently supports: "​UPI"  Required 

parameters:  String  Merchant’s VPA  Required 

payeeVpa 

parameters:  String  User-facing merchant name  Required 

payeeName 

parameters: referenceUrl  String  Merchant website URL for this  Optional 

specific transaction. 

parameters:  String  4 digit merchant category code  Required 

 
v0.2 India EAP 
9 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

mcc 

parameters:  String  Unique order ID generated by the  Required 

transactionReferenceId  Merchant. 
(tr) 

parameters:  String  Unique transaction ID generated by  Optional 

transactionId (tid)  the merchant’s PSP. 

tokenSpecification
 
Property  Type  Description  Required/Optional 

type  String  Currently supports: D

​ IRECT   Required 

transactionInfo
 
Property  Type  Description  Required/Optional 

countryCode  String  Only "IN" value currently supported for  Required 

UPI payment. 

currencyCode  String  currency in which you are accepting the  Required 

payment. Only "INR" value currently 
supported. 

totalPrice  String  Decimal amount for the payment.  Required 

totalPriceStatus  String  Only "FINAL" value currently supported.  Required 

transactionNote  String  Additional comments on transaction.  Optional 

Response 
 
Example 
{
​"apiVersion"​:​ ​2,
​"apiVersionMinor"​:​ ​0,
​"paymentMethodData"​:​ {
​"type"​:​ ​"UPI",

 
v0.2 India EAP 
10 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

​"tokenizationData"​:​ {
​"type"​:​ ​"DIRECT"
​"token"​:​ ​<<UTF-8 encoded token string>>
}
​},
}

The value of “token” is an encoded string of a JSON object. Substituting it with the real string,
the example is:
{
"apiVersion" : 2,
"apiVersionMinor" : 0,
"paymentMethodData" : {
"type" : "UPI",
"tokenizationData" : {
"type" : "DIRECT",
"token" :
"{\"protocolVersion\":\"ECv1\",\"signature\":\"TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFO
NFh7HgQ\",\"signedMessage\":\"{\\\"messageExpiration\\\":\\\"1234567890000\\\",\\\"
paymentMethod\\\":\\\"UPI\\\",\\\"paymentMethodDetails\\\":{\\\"payeeVpa\\\":\\\"me
rchant@psp\\\",\\\"status\\\":\\\"SUBMITTED\\\",\\\"transactionId\\\":\\\"AXI123\\\
",\\\"transactionInfo\\\":{\\\"currencyCode\\\":\\\"INR\\\",\\\"totalPrice\\\":\\\"
13.00\\\",\\\"totalPriceStatus\\\":\\\"FINAL\\\",\\\"transactionNote\\\":\\\"Transa
ction Description\\\"},\\\"transactionReferenceId\\\":\\\"1234\\\"}}\"}",
}
}
}

paymentMethodData

 
The message returned by Google Pay in the P ​ aymentData​ response is a UTF-8 encoded 
serialized JSON​ dictionary containing the following fields: 
 
Property  Type   Description 

type   String  Type of payment, currently supports: ​UPI 

tokenizationData:  String  Currently support: D

​ IRECT ​(indicates that the response 
type  /Enum  can be handled directly by the merchant) 

 
v0.2 India EAP 
11 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

tokenizationData:  String  UTF-8 encoded serialized JSON string containing payment 

token  response data specific to both the tokenization and 
payment types. Check the message specification for token 
and signedMessage for its JSON structure. 
 

token

 
Example 
{
"protocolVersion": "ECv1",
"signature": "TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
"signedMessage":​ <
​<UTF-8 encoded paymentMethod string>> 
}
 
 
 
Property  Type   Description 

protocolVersion  String  The encryption/signing scheme used. For example, "ECv1." 

signature  String  Verifies that the message came from Google Pay. The 
signature is created using ECDSA. 

signedMessage  String  The signature verified response generated by Google Pay. 

 
signedMessage
 
Example 
{ 
​
"messageExpiration": "1234567890000",
"paymentMethod": "UPI",
"paymentMethodDetails": ​{
"payeeVpa": "merchant@psp",
"status": "SUBMITTED",
"transactionId": "AXI123",
"transactionInfo":​ {
"currencyCode": "INR",
"totalPrice": "13.00",

 
v0.2 India EAP 
12 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

"totalPriceStatus": "FINAL",
"transactionNote": "Transaction Description"
​}​,
"transactionReferenceId": "1234"
} 
} 
 

 
Property  Type   Description 

messageExpiration String  Response expiration as milliseconds since the epoch, UTC. The 
merchant must not trust any responses after the expiration 
time. 

paymentMethod String  The method used for this transaction. Currently only "UPI" is 
supported. 

paymentMethodDetails String  Details of the UPI transaction. 

paymentMethodDetails String  The merchant destination VPA as specified in the request. The 
: payeeVpa merchant must verify this and other fields to guard against 
security risks.  

paymentMethodDetails String  Status of the transaction. This can be either "SUCCESS" for a 
: status completed transaction, "SUBMITTED" for a pending transaction, 
or "FAILURE." 

paymentMethodDetails String  The transaction ID specified in the request. It refers to the tid 
: transactionId parameter in the intent call. 

paymentMethodDetails String  The transaction ID generated by the PSP and either provided in 
: the request or added automatically by Google Pay. It refers to 
transactionReference the tr parameter in the intent call. 
Id

paymentMethodDetails String  The transaction information from the request. The merchant 
: transactionInfo must verify these values to guard against security risks. 

Verifying The Signed Response 

For verifying the UPI signature please refer to the d
​ eveloper documentation website​. 
 

Identity API 
 

 
v0.2 India EAP 
13 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

In case you have implemented Google Sign-in APIs, you can expect the same ID token in the response of 
this API. To use this API, you will need to setup a Google Cloud project via the G
​ oogle Cloud console​, and 
setting up OAuth 2.0 (see g ​ uide​), if that doesn't exist already. 
 
When the API is called, a bottom sheet will be shown to ask the user if they wanted to sign in to the 
microapp. If the user agrees, their consent will be recorded, and microapp will show up in user’s 
https://accounts.google.com/permissions​ page. After that, subsequent calls to requestIdentity will return 
valid token without prompting for user’s consent. In the event that user manually revoke microapp’s 
sign-in permission in h​ ttps://accounts.google.com/permissions​, we will start showing bottom sheet to 
ask for user consent the next time requestIdentity is called. 
 
requestIdentity().then(response => {...})

Response 
 
Property  Type   Description 

identityToken string  Encoded base64 of JSON Web Token 

Note: the API currently returns a mock response, in the form of an expired token with a valid 
signature. Once this is replaced with the actual response, you must add the validation logic for 
security.  

identityToken
 
Example 
 
{
"iss": "accounts.google.com",
"at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
"email_verified": "true",
"sub": "10769150350006150715113082367",
"azp": "1234987819200.apps.googleusercontent.com",
"email": "[email protected]",
"aud": "1234987819200.apps.googleusercontent.com",
"iat": 1353601026,
"exp": 1353604926,
"nonce": "0394852-3190485-2490358",
"hd": "example.com"
}
 
 
 
v0.2 India EAP 
14 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

Claim  Provided  Description 

iss  always  The Issuer Identifier for the Issuer of the response. Always 
https://accounts.google.com or accounts.google.com for Google ID 
tokens. 

at_hash    Access token hash. Provides validation that the access token is tied to the 
identity token. If the ID token is issued with an access token in the server 
flow, this is always included. This can be used as an alternate mechanism 
to protect against cross-site request forgery attacks, but if you follow ​Step 
1​and S
​ tep 3​ it is not necessary to verify the access token. 

email_verifie   True if the user's e-mail address has been verified; otherwise false. 
d 

sub  always  An identifier for the user, unique among all Google accounts and never 
reused. A Google account can have multiple emails at different points in 
time, but the sub value is never changed. Use sub within your application 
as the unique-identifier key for the user. 

azp    The client_id of the authorized presenter. This claim is only needed when 
the party requesting the ID token is not the same as the audience of the ID 
token. This may be the case at Google for hybrid apps where a web 
application and Android app have a different client_id but share the same 
project. 

email    The user's email address. This may not be unique and is not suitable for 
use as a primary key. Provided only if your scope included the string 
"email". 

profile    The URL of the user's profile page. Might be provided when: 
● The request scope included the string "profile" 
● The ID token is returned from a token refresh 
When profile claims are present, you can use them to update your app's 
user records. Note that this claim is never guaranteed to be present. 

picture    The URL of the user's profile picture. Might be provided when: 
● The request scope included the string "profile" 
● The ID token is returned from a token refresh 
When picture claims are present, you can use them to update your app's 
user records. Note that this claim is never guaranteed to be present. 

 
v0.2 India EAP 
15 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

name    The user's full name, in a displayable form. Might be provided when: 
● The request scope included the string "profile" 
● The ID token is returned from a token refresh 
When name claims are present, you can use them to update your app's 
user records. Note that this claim is never guaranteed to be present. 

aud  always  Identifies the audience that this ID token is intended for. It must be one of 
the OAuth 2.0 client IDs of your application. 

iat  always  The time the ID token was issued, represented in Unix time (integer 
seconds). 

exp  always  The time the ID token expires, represented in Unix time (integer seconds). 

nonce    The value of the nonce supplied by your app in the authentication request. 
You should enforce protection against replay attacks by ensuring it is 
presented only once. 

hd    The hosted G Suite domain of the user. Provided only if the user belongs 
to a hosted domain. 
 

Decoding and Verification 

You can use the following methods from jwt.io to operate on the identityToken: 
● decode - to decode the token 
● verify - to verify the token (​more details here​) 

Error codes 
Coming soon. 

Phone number API 

You can use this API to get the phone number the user registered with the Google Pay app. We will return 
the phone number as a signed JWT, which you can verify by using one of the JWT libraries listed at ​jwt.io 
and the Microapps public key (​PEM​, ​JWK​). 
 
When the API is called, the user will be asked if they want to share their phone number with the microapp. 
If the user agrees, their consent will be recorded, and subsequent calls to the API will return the user’s 
phone number.  
 
 
v0.2 India EAP 
16 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

microapps.getPhoneNumber(request).then(response => {...})

 
This API should be invoked at each time in your microapp flow where the phone number is required. The 
Google Pay app allows users to update their phone numbers, therefore calling the API for each session 
ensures that the freshest phone number is provided. 

Request 

Property  Type   Description 

nonce string  (Optional) If provided, the nonce will be present in the response. If 
you use a nonce, you should check if the nonce in the response is 
identical to the one you put here. 
 

Response 

Property  Type   Description 

phoneNumberJwt string  JSON Web Token, encoded in base64. 

 
Note: The returned token is *not* OpenID Connect compliant. We may be making it OIDC-compliant in the 
future, but for now it does not adhere to the standard. 
 
Example 
 
{
"iss": "microapps.google.com",
"aud": "your.microapp.id",
"iat": 1353601026,
"exp": 1353604926,
"nonce": "0394852-3190485-2490358", // If provided
"phone_number" : ​"+56 (2) 687 2400."
"phone_number_verified": "true",
}

phoneNumberJwt
 

Claim  Provided  Description 

 
v0.2 India EAP 
17 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

iss  always  The Issuer Identifier for the Issuer of the response. Always 
https://microapps.google.com or https://microapps.google.com.. 

aud  always  Identifies the audience that this ID token is intended for. It must be one 
of the OAuth 2.0 client IDs of your application. 

iat  always  The time the ID token was issued, represented in Unix time (integer 
seconds). 

exp  always  The time the ID token expires, represented in Unix time (integer 
seconds). 

nonce  always if  The value of the nonce supplied by your app in the authentication 
developer  request. If you provided one when calling the API, it should be returned 
provided  unchanged to you. You should enforce protection against replay attacks 
by ensuring it is presented only once. 

phone_numb   The user's phone number. 

er 

phone_numb   True if the user's phone number has been verified; otherwise false. 
er_virief 

Decoding and Verification 

The signed JWT can verified by using at j​ wt.io​ (web interface for development) or any of the of the JWT 
libraries listed at there. The Microapps public key is avaliable in both P
​ EM​ and ​JWK​ format. 

Error codes 
Coming soon. 
 
 

 
v0.2 India EAP 
18 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

Sharing API 
The sharing API is used to share custom messages to the other users. 
 
The URL must be a deep-link to the microapp from which it is called (see D
​ eep-linking​): 
 
● https://microapps.google.com/<microapp_id>[?params] 
 
Example 
requestSharing({
text: “Check out this awesome microapp!”,
url: "https://microapps.google.com/com.google.internal.hwj.test?myparam=value",
});
 

Location API 
The location API is used for getting user’s geolocation. The API returns the GPS coordinate 
asynchronously through P ​ romise​. When the API is called, it will ask the user to grant device location 
permission to the Google Pay app (if the permission is not granted yet). 
 
getCurrentLocation().then((location) => { … });

Response 
Example 
{
“latitude”: 1.234,
“longitude”: 5.678,
}
 
Property  Type   Description 

latitude number  The latitude of the current location 

longitude number  The longitude of the current location 

 

Orders API 
Order details can be recorded either from the client or the server, but the representation of an order in 
JSON remains the same. 

 
v0.2 India EAP 
19 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

createOrder 
The following client API can be used to record a new order on the client: 
createOrder(order);
 
The server API can be accessed as follows: 
POST/v1alpha/orders 

URL: https://microapps.googleapis.com/v1alpha/orders/
 
 
Example - client request 
{
title: "Latte @ barista floor 9",
imageUrl: "https://barista.org/latte.jpg",

items: {
title: "Latte",
price: {
currency: "INR",
value: “100.0”
},
},

total: {
currency: "INR",
value: “100.0”
},

status: {
type: "COMPLETED"
},

payments: [{
id: "ac6d65fa-e427-47c7-8631-21bd976b09c6"
}],

Merchant: {
Id: “BDD2DN6TXCVKFLR3”
}
}
 
 
v0.2 India EAP 
20 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

 
 
 
 
Example - server request
{
"title": "Google Hat"
"imageUrl": "https://example.com/image.png",
"items": {
"price": {
"currency": "INR",
"value": "90.00"
},
},
"status": {
"type": "PENDING"
},

"total": {
"currency": "INR",
"value": "90.00"
},
"payments": [{
"id": "order-1562312741089"
}],
Merchant: {
Id: “BDD2DN6TXCVKFLR3”
}
}
 
 
 
Example - response 
{
"name": "orders/chZEF80YOSaSCykogJS5Ow==",
"items": [{
"title": "Google Hat",
"price": {
"currency": "INR",
"value": "90.00"
}
}],
"status": {
"type": "PENDING"
},

 
v0.2 India EAP 
21 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

"payments": [{
"id": "order-1562312741089"
}],
"title": "order-1562312741089",
"imageUrl": "https://example.com/image.png"
} 
 
 
Property  Type  Description  Required v. 
Optional 

name string  The resource name of the order, with the form of  Optional 
`orders/{order_id}`. This field should not be set when 
creating an order. 

title string  The title of the order  Required 

subtitle string  The subtitle of the order  Optional 

imageUrl string  A URL to an image representative of the order  Optional 

total Amount  The total amount of the order  Optional 

items Item  A list of items of the order. A maximum of 100 items  Optional 
are allowed. 

status : string  The type of the status. Only the following string  Optional 
type values are acceptable: STATUS_TYPE_UNSPECIFIED, 
PENDING, CONFIRMED, WAITLISTED, PREPARING, 
SHIPPED, OUT_FOR_DELIVERY, COMPLETED, 
CANCELLED 

attachments Attachment  A list of attachments to the order (e.g. a PDF invoice).  Optional 
A maximum of 10 attachments are allowed. 

actions Action  A list of actions related to the order that a user can   
take (e.g. cancel, reorder etc.) A maximum of 10 
actions are allowed. 

payments : string  List payment IDs associated with the order. For UPI  Required 
id transactions in India, this is the transaction reference 
ID.  
 
Note: Currently, we only use the first element in the list. 

Merchant : string  Google assigned Merchant ID  Required. 

id
 

 
v0.2 India EAP 
22 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

Amount
 
currency  string  The currency as a 3-letter ISO 4217 alphabetic code.  Required 
See:​ https://en.wikipedia.org/wiki/ISO_4217 

value  string  String representation of the amount in the specified  Required 

currency. 
 
 
Item
 
title  string  The title of the item.  Required 

subtitle  string  The subtitle of the item.  Optional 

quantity  integer  The number of items of this type that are part of the  Optional 
order 

price  Amount  The price of the item.  Optional 

travelLeg  TravelLe Acctional detals for the item, if this is a travel ticket  Optional 
g 
 
 
Attachment
 
label  string  The label for the attachment.  Required 

type  string  The type of the attachment. Only the following string  Required 
values are allowed: 
ATTACHMENT_TYPE_UNSPECIFIED, PDF 

url  string  A URL for the attachment. The URL needs to start  Required 
with “https://”. For type PDF, the URL needs to serve a 
response with Content-type “application/pdf”. 
 
 
Action
 

 
v0.2 India EAP 
23 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

label  string  The label for the action.  Required 

url  string  A URL to open for the user to take the action. The  Required 
following URL prefixes are supported: 
“​https://microapps.google.com/{microapp_id​}” to 
take the user to a microapp. 
 
TravelLeg
 
origin  string  The label for the action.  Required 

destination  string  A URL to open for the user to take the action. The  Required 
following URL prefixes are supported: 
“​https://microapps.google.com/{microapp_id​}” to 
take the user to a microapp. 

bookingReference  string  A booking reference number for the travel leg.  Optional 

passengers  Passenger  A list of passengers on this travel leg. A maximum  Optional 

of 10 passengers are allowed . 
 
Passenger
 
passengerName  string  The name of the passenger  Required 

additionalInfo  string  Additional information about the passenger on this  Optional 

travel leg. 

getOrder 
This API allows a pre-existing order to be fetched from the server. It can be accessed as follows: 
 
GET/v1alpha/orders/orderId

URL: https://microapps.googleapis.com/v1alpha/orders/:orderId

 
Example 
 

 
v0.2 India EAP 
24 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

Request 
https://microapps.googleapis.com/v1alpha/orders/chZEF80YOSaSCykogJS5Ow==
 
Response
{
"name": "orders/chZEF80YOSaSCykogJS5Ow==",
"items": [{
"title": "Google Hat",
"price": {
"currency": "INR",
"value": "0.0"
}
}],
"status": {
"type": "COMPLETED"
},
"payments": [{
"id": "order-1562312741089"
}],
"title": "order-1562312741089",
"imageUrl": "https://example.com/image.png"
}

updateOrder 
This API allows a pre-existing order to be updated from the server. It can be accessed as follows: 
 
PATCH/v1alpha/orders/orderId?updateMask=fieldName

URL:
https://microapps.googleapis.com/v1alpha/orders/:orderId?updateMask=fieldName
Standard field mask value is supported for u
​ pdateMask​ parameter. M
​ ore guidance about ​field
mask​ can be found ​here​. 
 
 
Example 
 
Request 
https://microapps.googleapis.com/v1alpha/orders/chZEF80YOSaSCykogJS5Ow==?update
Mask=status

{
 
v0.2 India EAP 
25 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

"status": {
"type": "COMPLETED"
}
}
 
Response
{
"name": "orders/chZEF80YOSaSCykogJS5Ow==",
"items": [{
"title": "Google Hat",
"price": {
"currency": "INR",
"value": "0.0"
}
}],
"status": {
"type": "COMPLETED"
},
"payments": [{
"id": "order-1562312741089"
}],
"title": "order-1562312741089",
"imageUrl": "https://example.com/image.png"
}
 

Messages API 
Please refer to the C
​ ommunications API​. 
 
 
Deep-linking 
In addition to finding and launching microapps from inside the Google Pay app, each microapp will also 
be associated with a web link that can be used to link directly into the microapp from the web, or a QR 
code. 
 
The following URL can be used to link into a microapp (simply replacing the "your.microapp.id" with the 
desired ID of the target microapp): 
 
https://microapps.google.com/​your.microapp.id
 
 
v0.2 India EAP 
26 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

You can share this link across your own communications / properties to bring the user to your microapp, 
or to a landing page on the web where they will have the option to download the Google Pay app, if they 
don't already have it installed. 
 
Parameters can be passed to the microapp by simply appending a query string to the above URL like so: 
 
https://microapps.google.com/your.microapp.id​?param1=abc&param2=def
 
The parameters will be added to the microapp's registered base URL internally before loading it in Google 
Pay. 
 
Important​: Microapps must not trust any parameter in a link, or any other user input in the app, as that is 
easily spoofable. It is strongly recommended to follow best practices on web application security, incl. 
about input validation. 
 

Performance Optimization 

Initial page load 

Initial page load time of a microapp is essential for a good user experience. A fast landing page leads to 
higher conversions and user growth. The following principles are recommended for optimizing the page 
load speed. 
 
● Reduce the page size. Minimize the amount of code and resources to be loaded for the initial 
page. 
● If possible, avoid dynamic content. Make the landing page relative static and cacheable. A 
cacheable landing page will make subsequent app loads faster. 
● If dynamic content cannot be avoided, 
○ If the content is important for the t​ ime of interactive​, try​ server side rendering t​ o serve it 
with initial page load to avoid extra round trips, but please note the server side shouldn’t 
perform heavy work to process the dynamic content and it will slow down the app load. If 
that’s the case you may need to reconsider the landing page UX design. 
○ If the dynamic part is optional, show static part (refer to app shell model in S ​ ervice 
worker section​) to user first and then use c​ lient side rendering​ to load the dynamic 
content.  

Page transitions 
● Once the landing page is loaded, use ​client side rendering​ for subsequent page navigations. This 
improves efficiency and reduces the amount of server side page calls. 
● Preload/Prefetch​ resources for subsequent rendered page. 

 
v0.2 India EAP 
27 
 GOOGLE CONFIDENTIAL & PROPRIETARY 
 

Service Workers 
Service workers​ have the potential to greatly improve initial page loading performance by caching the 
JS/CSS/static resources necessary to start the initial page. Additionally, the a​ pp shell model​ allows some 
content to be displayed immediately while data is fetched asynchronously. The progressive change 
ensures a more native-app-like experience even with flaky connections. 
 
● Note:​ ServiceWorkers are not supported in all versions of the runtime (incl. on iOS WebView). 
Please ​check service worker api availability​ before using it to ensure the app can work without 
service worker support.  
 

Feature policies 
Microapp iframes are enforced by using ​feature policies​ to disable the negative features for providing 
good performance and user experiences. These negative features include: 
 
● document.write​ - blocks Document.write API 
● sync-xhr​ - disallows the use of synchronous XMLHttpRequests 
● oversized-images​ ​unoptimized-images​ - optimizes image handling 
 
Please test your microapp website with f​ eature policy tester devtools​ to ensure the app doesn’t have 
policy violations before publishing it. 

 
v0.2 India EAP 
28