Initiate Payment

Stay organized with collections Save and categorize content based on your preferences.

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.