Initiate Payment

Using this API, you can initiate the payment request from customers in your purchase flow. In the message payload, you can add a specific business Virtual Payment Address (VPA) in which you want to receive the payment. If you do not pass the value in the vpa field, the default VPA (added during merchant onboarding) will receive the payment.

To initiate the payment, make the following POST request to the API:

POST https://nbupayments.googleapis.com/v1/merchantPayments:initiate

{

      // googleMerchantId should be set. This ID is globally unique across all Google Pay merchants.
      “merchantInfo”: {
            “googleMerchantId”: “BREKJWNFNFLS”
      },
      “userInfo”: {
            // Phone no. of the payer in E.164 format
            “phoneNumber”: “+919876543210”
       },
       “merchantTransactionDetails”: {
            // Transaction ID from Google Pay partner. This must be unique for every transaction done by the partner and should be in accordance with the syntax agreed upon with the merchant PSP.
            “transactionId”: “transactionId”,
            // Amount to be paid by user
            “amountPayable”: {
                  // The 3-letter currency code defined in ISO 4217.
                  “currencyCode”: “INR”,
                  // The whole units of the amount.
                  // For example if currencyCode is "INR", then 1 unit is one rupee.
                  “units”: 100,
                  // Number of nano (10^-9) units of the amount.
                  “nanos”: 0
            },
            // Description for the transaction.
            “description”: “Sample description”
            // UPI Payment Details of the merchant.
           “upiPaymentDetails”: {
                 // VPA where the payment needs to be done. Need to be specified only if it is different from the default VPA.
                 “vpa”: “abc@xyz”
           }
           // Details about GST.
           "gst": {
                 // Merchant GSTIN (Goods and Services Tax Identification Number).
                 "gstin": "29ABCDE1234F2Z5"
                 "gstBreakUp": {
                       // Goods and Services Tax.
                       "gst": {
                             // The 3-letter currency code defined in ISO 4217.
                             “currencyCode”: “INR”,
                             // The whole units of the amount.
                             // For example if currencyCode is "INR", then 1 unit is one rupee.
                             “units”: 10,
                             // Number of nano (10^-9) units of the amount.
                             “nanos”: 0
                       }
                       // Central Goods and Services Tax.
                       "cgst": {
                             // The 3-letter currency code defined in ISO 4217.
                             “currencyCode”: “INR”,
                             // The whole units of the amount.
                             // For example if currencyCode is "INR", then 1 unit is one rupee.
                             “units”: 5,
                             // Number of nano (10^-9) units of the amount.
                             “nanos”: 0
                       }
                       // State Goods and Services Tax.
                       "sgst": {
                             // The 3-letter currency code defined in ISO 4217.
                             “currencyCode”: “INR”,
                             // The whole units of the amount.
                             // For example if currencyCode is "INR", then 1 unit is one rupee.
                             “units”: 3,
                             // Number of nano (10^-9) units of the amount.
                             “nanos”: 0
                       }
                       // Integrated Goods and Services Tax.
                       "igst": {
                             // The 3-letter currency code defined in ISO 4217.
                             “currencyCode”: “INR”,
                             // The whole units of the amount.
                             // For example if currencyCode is "INR", then 1 unit is one rupee.
                             “units”: 1,
                             // Number of nano (10^-9) units of the amount.
                             “nanos”: 0
                       }
                       // GST compensation cess.
                       "cess": {
                             // The 3-letter currency code defined in ISO 4217.
                             “currencyCode”: “INR”,
                             // The whole units of the amount.
                             // For example if currencyCode is "INR", then 1 unit is one rupee.
                             “units”: 1,
                             // Number of nano (10^-9) units of the amount.
                             “nanos”: 0
                       }
               }
           }
           "invoice": {
               "invoiceNumber": "Invoice456"
               // The time of invoice in RFC 3339 format. Eg, 2017-02-15T16:20:30+05:30 for IST timezone; 2017-02-15T10:50:30Z for UTC.
               "invoiceTime": “2017-02-15T10:50:30Z”
           }
     },

     // The time at which the request expires in RFC 3339 format. Eg, 2017-02-15T16:20:30+05:30 for IST timezone; 2017-02-15T10:50:30Z for UTC.
     “expiryTime”: “2017-02-15T10:50:30Z”,
     // The platform at which the request is originating
     “originatingPlatform”: “ANDROID_APP”
}

Parameters

User info

The following data parameter for the userInfo object must be passed in the API request:

Parameters	Type of value	Description	Required/Optional
`phonenumber`	String	User mobile number in E.164 format.	Required

Merchant info

The following data parameter for the merchantInfo object must be passed in the API request:

Parameters	Type of value	Description	Required/Optional
`googleMerchantId`	String	Google assigned merchant ID (Generated at onboarding time).	Required

Merchant transaction details

The following data parameters for the merchantTransactionDetails object must be passed in the API request:

Parameters	Type of value	Description	Required/Optional
`transactionId`	String	A unique transaction ID generated by the partner for every transaction. This ID should be in accordance with the syntax agreed upon with the merchant PSP.	Required
`description`	String	Description for a transaction.	Optional

UPI payment details

To add a specific VPA, you can pass the following data parameter in the upiPaymentDetails object.

Parameters	Type of value	Description	Required/Optional
`vpa`	String	Business Virtual Payment Address (VPA) that receives the payment. Specify only if the VPA is different from the default one.	Optional

Amount payable

The following are the data parameters to pass into the amountPayable object nested under the merchantTransactionDetails object.

Parameters	Type of value	Description	Required/Optional
`currencyCode`	String	The currency in which you want to make payment.	Required
`units`	Number	Amount to be paid.	Required
`nanos`	Number	Number of nano (10^-9) units of the amount.	Required

Set expiry time

Pass the time at which the payment request expires in the expiryTime key. The time must be defined in the RFC 3339 format (example 2018-06-02T11:50:30Z). This field is optional.

Set originating platform

You must set the originating platform by passing the enum value for originatingPlatform key. This field is required. The following are the possible values for originatingPlatform key.

ANDROID_APP
ANDROID_WEB
IOS_APP
IOS_WEB
INSTORE_POS
DESKTOP
IVR
OTHER

Gst

The following are the data parameters to pass into the gst object nested under the merchantTransactionDetails object.

Parameters	Type of value	Description	Required/Optional
`gstin`	String	Merchant GSTIN (Goods and Services Tax Identification Number).	Optional

Gst

The following are the data parameters to pass into the gst object nested under the gstBreakup object.

Parameters	Type of value	Description	Required/Optional
`currencyCode`	String	The currency in which you want to make payment.	Required
`units`	Number	GST amount	Required
`nanos`	Number	Number of nano (10^-9) units of the amount.	Required

Cgst

The following are the data parameters to pass into the cgst object nested under the gstBreakup object.

Parameters	Type of value	Description	Required/Optional
`currencyCode`	String	The currency in which you want to make payment.	Required
`units`	Number	CGST amount	Required
`nanos`	Number	Number of nano (10^-9) units of the amount.	Required

Igst

The following are the data parameters to pass into the igst object nested under the gstBreakup object.

Parameters	Type of value	Description	Required/Optional
`currencyCode`	String	The currency in which you want to make payment.	Required
`units`	Number	IGST amount	Required
`nanos`	Number	Number of nano (10^-9) units of the amount.	Required

Sgst

The following are the data parameters to pass into the sgst object nested under the gstBreakup object.

Parameters	Type of value	Description	Required/Optional
`currencyCode`	String	The currency in which you want to make payment.	Required
`units`	Number	SGST amount	Required
`nanos`	Number	Number of nano (10^-9) units of the amount.	Required

Cess

The following are the data parameters to pass into the cess object nested under the gstBreakup object.

Parameters	Type of value	Description	Required/Optional
`currencyCode`	String	The currency in which you want to make payment.	Required
`units`	Number	Cess amount	Required
`nanos`	Number	Number of nano (10^-9) units of the amount.	Required

Invoice

The following are the data parameters to pass into the invoice object nested under the merchantTransactionDetails object.

Parameters	Type of value	Description	Required/Optional
`invoiceNumber`	String	The number on the invoice	Optional
`invoiceTime`	String	The time of invoice in RFC 3339 format. Eg, 2017-02-15T16:20:30+05:30 for IST timezone; 2017-02-15T10:50:30Z for UTC.	Optional

Response

Success

If successful, the POST request returns a 200 OK HTTP status code, including an empty JSON.

Failure

The API returns the following response if the request fails:

{
  “error”: {
    “code”: 400,
    “status”: “INVALID_ARGUMENT”,
    “message”: “Invalid phone number”
  }
}

API specific error codes

Code	Title	Description
403	PERMISSION_DENIED	Merchant is not authorized.
400	INVALID_ARGUMENT	Request contains invalid arguments.
404	NOT_FOUND	User was not found.
404	NOT_FOUND	Merchant was not found.
409	ALREADY_EXISTS	Duplicate transaction ID.
400	FAILED_PRECONDITION	Merchant has not setup to receive payments.