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