APIs for integration

This section lists all the APIs available for integration, and how to use them.

Setting API version

Setting the API version applies to all the APIs covered in this section.

Property Type Description Required / Optional
apiVersion Int Must be set to '2' to support the current API implementation Required
apiVersionMinor Int Must be set to '0' for the current implementation (it will be incremented on every backward compatible change to the API) Required

Using the APIs

isReadyToPay

Use this API to check the availability of a compatible version of Google Pay on the device, with registered payment methods.

Request

Example

"apiVersion":2,
"apiVersionMinor":0,
"allowedPaymentMethods":[
  {
    "type":“CARD",
    “parameters”:{
       "allowedCardNetworks":[“VISA”, “MASTERCARD”],
     }
  },
  {
    "type":"UPI"
  }
]

allowedPaymentMethods
Property Type Description Required/Optional
type String Payment methods accepted by merchant

Currently supports:UPI, CARD

Required
allowedCardNetworks String Array Payment methods accepted by merchant

Currently supports:VISA, MASTERCARD

Required, if type == CARD

Response

The response is a boolean. If the result returns FALSE, the merchant app shouldn't attempt to accept payments. If the result returns TRUE, the merchant app can request the user to proceed with the payment.

loadPaymentData

Use this API to make an asynchronous call to Google Pay for facilitating the payment. The API returns a result in onActivityResult. The caller must implement onActivityResult to handle the PaymentDataResponse.

Request

Example

{
  "apiVersion":2,
  "apiVersionMinor":0,
  "allowedPaymentMethods":[
    {
      "type":"UPI",
      "parameters":{
         "payeeVpa":"merchant@psp",
         "payeeName":"Merchant Name",
         "referenceUrl":"https://www.merchant.com/transaction/12345",
         "mcc":"0000",
         // Merchant generated transaction ID.
         // It is the tr parameter in the intent call.
         "transactionReferenceId":"12345",
         // PSP generated order ID. It is the tid parameter in the intent call.
         "transactionId":"AXI123"
      }
     "tokenizationSpecification":{
        "type":"DIRECT"
      }
    },
  ],
  "transactionInfo":{
      "totalPriceStatus":"FINAL",
      "total Price":"13.00",
      "currencyCode":"INR",
      "transactionNote":"Note",
  }
}
allowedPaymentMethods
Property Type Description Required/Optional
type String Currently supports:UPI, CARD Required
parameters:payeeVpa String Merchant’s VPA Required
parameters:payeeName String User-facing merchant name Required
parameters:referenceUrl String Merchant website URL for this specific transaction Optional
parameters:mcc String 4 digit merchant category code Required
parameters:transactionReferenceId (tr) String Unique order ID generated by the Merchant. It refers to the tr parameter in the intent call. Required
parameters:transactionId (tid) String Unique transaction ID generated by the merchant’s PSP. It refers to the tid parameter in the intent call. Optional
parameters:gstIdentificationNumber String Merchant GSTIN (Goods and Services Tax Identification Number) Optional
parameters:gstBreakup String Break-up of GST amount charged Optional
parameters:gstBreakUp:gst String Total goods and services tax Optional
parameters:gstBreakUp:cgst String Central goods and services tax Optional
parameters:gstBreakUp:sgst String State goods and services tax Optional
parameters:gstBreakUp:igst String Integrated goods and services tax Optional
parameters:gstBreakUp:cess String GST compensation cess Optional
parameters:invoiceNumber String Invoice Number. Only mandatory for GST use case. Optional
parameters:invoiceDate String Timestamp of invoice, in RFC 3339 format, e.g. "2014-07-30T10:43:17+05:30". Only mandatory for GST use case. Optional
tokenSpecification
Property Type Description Required/Optional
type String Currently supports:PAYMENT_GATEWAY, DIRECT

If you use a Payment Gateway (PG) integrated with Google Pay:
- define the type as PAYMENT_GATEWAY
- pass the values for gateway and gatewayMerchantID

If you are passing the payment credentials to the processor directly, define the type as DIRECT

Required
gateway String Name of the Payment Gateway with which the merchant has integrated Required, if type == PAYMENT_GATEWAY
gatewayMerchantId String Unique ID for the merchant provided by the Payment Gateway Required, if type == PAYMENT_GATEWAY
gatewayTransactionId String PG generated transaction ID for an order. It's used to identify an order/transaction at the PG’s end. Required
gateway:merchantName String Fields to be passed to PG. Use the key-value pair format as <gateway-name> : <field-name> .

Example:
"newco-gateway:merchantName":"MyFoodApp"
"newco-gateway:transactionId":"3405795"

Optional
transactionInfo
Property Type Description Required/Optional
currencyCode String Currency in which you are accepting the payment. Only "INR" value currently supported. Required
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",
      "tokenizationData":{
        "type":"DIRECT"
        "token":<<UTF-8 encoded token string>>
      }
  },
}

paymentMethodData
The message returned by Google Pay in the PaymentData response is a UTF-8 encoded serialized JSON dictionary containing the following fields:
Property Type Description
type String Type of payment. Currently supports:UPI, CARD
tokenizationData:type String / Enum Currently supports:DIRECT (indicates that the response can be handled directly by the merchant)
tokenizationData:token String UTF-8 encoded serialized JSON string containing payment response data specific to both the tokenization and payment types
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 for UPI payments

Example

{
    "messageExpiration":"1234567890000",
    "paymentMethod":"UPI",
    "paymentMethodDetails":{
        "payeeVpa":"merchant@psp",
        "status":"SUBMITTED",
        "transactionId":"AXI123",
        "transactionInfo":{
            "currencyCode":"INR",
            "totalPrice":"13.00",
            "totalPriceStatus":"FINAL",
            "transactionNote":"Transaction Description"
        },
        "transactionReferenceId":"1234"
    }
}

Property Type Description
messageExpiration String Response expiration in milliseconds since the epoch, UTC. The merchant must not trust any responses after the expiration time.
paymentMethod String The method used for this transaction:UPI.
paymentMethodDetails String Details of the UPI transaction
paymentMethodDetails:payeeVpa String The merchant destination VPA as specified in the request. The merchant must verify this and other fields to guard against security risks.
paymentMethodDetails:status String Status of the transaction. This can be either "SUCCESS" for a completed transaction, "SUBMITTED" for a pending transaction, or "FAILURE."
paymentMethodDetails:transactionId String The transaction ID specified in the request. It refers to the tid parameter in the intent call.
paymentMethodDetails:transactionReferenceId String The transaction ID generated by the PSP, and provided either in the request or added automatically by Google Pay. It refers to the tr parameter in the intent call.
paymentMethodDetails:transactionInfo String The transaction information from the request. The merchant must verify these values to guard against security risks.
signedMessage for card payments

Example

{
    "messageExpiration":"1234567890000",
    "paymentMethod":"CARD",
    "paymentMethodDetails":{
        "status":"SUBMITTED",
        "gatewayTransactionId":"order-id-generated-by-the-pg",
        "gatewayResponse":"{response from merchant's gateway.}",
    }
}
Property Type Description
messageExpiration String Response expiration in milliseconds since the epoch, UTC. The merchant must not trust any responses after the expiration time.
paymentMethod String The method used for this transaction:CARD.
paymentMethodDetails String Details of the card transaction.
paymentMethodDetails:status String Status of the transaction.
paymentMethodDetails:gatewayTransactionId String PG generated transaction ID for an order. It’s used to identify an order/transaction at the PG’s end.
paymentMethodDetails:gatewayResponse String Response from merchant’s gateway.