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”
           }
    },

      // 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

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.