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",
      }
     "tokenizationSpecification":{
        "type":"DIRECT"
      }
    },
  ],
  "transactionInfo":{
      "totalPriceStatus":"FINAL",
      "totalPrice":"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	Deprecated This field must be kept unset. 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**
Property	Type	Description
The message returned by Google Pay in the PaymentData response is a UTF-8 encoded serialized JSON dictionary containing the following fields:
`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

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

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.

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.