Inquire Invoice
  • 20 Aug 2023
  • 4 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Inquire Invoice

  • Dark
    Light
  • PDF

Article summary

Use the Inquire Invoice web service to Inquire about an invoice using the SmartLink interface.

Syntax

POST rest/InvoicesService/inquireInvoice

Service Specifications

Property and Information
  • Endpoint: inquireInvoice
  • Name: Inquire Invoice Service
  • Method: POST
  • Input Parameters: invoice, a JSON formatted object.
  • Parameters Type: Form parameters that need to be set in the body of the HTTP request.
  • Path: rest/InvoicesService/inquireInvoice. The path is prefixed with the SmartLink context root.

Input Parameters

ParameterDescription
merchantID
required
An alphanumeric value that represents the Merchant ID. The Payment Gateway operation team provides this value based on the merchant enrollment. 
  • Field Type: Alphanumeric
  • Length: 30
  • Sample Data: maisMerchant
authenticationToken
required 
An alphanumeric value that represents the Authentication Token. The Payment Gateway operation team provides this value based on the merchant enrollment. 
  • Field Type: Alphanumeric
  • Length: 255
  • Sample Data: YTIzYzBhZmU5OTI2MTU3ZGM5ZjgzYmI5 
invoiceID
required
An alphanumeric value that represents the Invoice ID which must be unique per invoice.
  • Field Type: Alphanumeric
  • Length: 60
  • Sample Data: 30231175

Sample Request

The Inquire Invoice service request should contain the details of the Invoice that you want to inquire about.

It is in JSON format and contains the following details:

  • authenticationToken
  • merchantID
  • invoiceID
invoice = {
	"authenticationToken" : "N2FiZDRmYTQzNDUzOGM0YTI4N2I5YmZm",
	"merchantID" : "testMercahnt",
	"invoiceID" : "56534333"
}

Output Parameters

ParameterDescription
rrn
optional
The reference retrieval number of the requested payment.

  • Field Type: Alphanumeric
  • Length: 50
  • Sample Data: 840201608161029435230000000000
approvalCode
optional
The approval Code of the requested payment.

  • Field Type: Alphanumeric
  • Length: 10
  • Sample Data: 0000125480 
cardType
optional
An alphanumeric value that represents the card type.

  • Field Type: Alphanumeric
  • Length: 20
  • Sample Data: Visa
cardNumber
optional
An alphanumeric value that represents the masked card Number.

  • Field Type: Alphanumeric
  • Length: 20
  • Sample Data: 401200******3335 
merchantID
required
An alphanumeric value that represents the Merchant ID given by SmartLink. Based on the merchant enrollment, the Payment Gateway operation team provides this value. 
  • Field Type: Alphanumeric
  • Length: 30
  • Sample Data: maisMerchant
authenticationToken
required
An alphanumeric value that represents the Authentication Token. Based on the merchant enrollment, the Payment Gateway operation team provides this value.
  • Field Type: Alphanumeric
  • Length: 255
  • Sample Data: YTIzYzBhZmU5OTI2MTU3ZGM5ZjgzYmI5
invoiceID
required
An alphanumeric value that represents the Invoice ID. The invoice ID is a unique value for each invoice. The value is the same as the Invoice ID sent in the request.
  • Field Type: Alphanumeric
  • Length: 60
  • Sample Data: 30231175
amount
required
A numeric value represents the invoice amount. The value is in ISO format with no decimal point.

  • Field Type: Numeric
  • Length: 9
  • Sample Data: 100
currency
required
The numeric ISO Code for the currency. The value is in ISO format with no characters.

  • Field Type: Numeric
  • Length: 3
  • Sample Data: 840

type
required

An alphanumeric value that represents the invoice type.
The expected invoice type could be: Payment or Pre-Auth & Completion.

     Possible values:
  • Payment
  • Pre-Auth & Completion

  • Field Type: Alphanumeric
  • Length: 30
  • Sample Data: Payment
authorizedAmount
conditional
A numeric value contains the actual paid amount of the invoice. The value is in ISO format with no decimal point.
This parameter may differ from the amount parameter in case MCP took a place during the transaction processing.

  • Field Type: Numeric
  • Length: 9
  • Sample Data: 71
authorizedCurrency
conditional
A numeric ISO Code for the actual currency used in the payment. The value is in ISO format with no characters.
This parameter may differ from the currency parameter in case MCP took a place during the transaction processing.

  • Field Type: Numeric
  • Length: 3
  • Sample Data: 400
expiryDateTime
required
A date that represents the computed expiry date and time.
The value is based on the expiryperiod parameter that you send in the request.
The value is formatted as dd-MM-yyyy HH:mm:ss.

  • Field Type: Date
  • Length: 9
  • Sample Data: 10-07-2021 08:29:20  
invoiceStatus
required
An alphanumeric value that represents the invoice status.

     Possible values:
  • PAID
  • REFUNDED
  • NEW
  • EXPIRED
  • PENDING_REFUND_APPROVAL

  • Field Type: Alphanumeric
  • Length: 10
  • Sample Data: REFUNDED 
refundAmount
conditional
A numeric value represents the refund amount for this invoice. This parameter is returned back in case there was a refund for the given invoice.

  • Field Type: Numeric
  • Length: 9
  • Sample Data: 100
completionAmount
conditional
A numeric value represents the completed amount for this invoice. This parameter is returned back in case there was a completion for the given invoice.

  • Field Type: Numeric
  • Length: 9
  • Sample Data: 100
refundCurrency
conditional
A numeric ISO Code represents the currency for the refundAmount parameter if provided back.

  • Field Type: Numeric
  • Length: 3
  • Sample Data: 840
completionCurrency
conditional
A numeric ISO Code represents the currency for the completedAmount parameter if provided back.

  • Field Type: Numeric
  • Length: 3
  • Sample Data: 840
paymentLink
required
A URL that represents the generated payment link. You can use this payment link to process transactions.

  • Field Type: URL
  • Length: 255
  • Sample Data: http://localhost:9081/URLShortener?t=chohyc
qrCode
conditional
A Base64 encoding format that represents the generated payment details. You can use this code to process the transactions.
The web service returns this code only when the value yes is sent in the generateQRCode parameter of the Create Invoice web service.

  • Field Type: Alphanumeric
  • Length: -
  • Sample Data:
iVBORw0KGgoAAAANSUhEUgAAAJYAAACWAQAAAAAUekxPAAABHklEQVR4
2u2WsRLDMAhDvfHL3mDjlz 30zpVI3FzaLfJYnwf8MoRIgNPmz3q1P1NZtGbDh8
2Z DGWWPHQLn8lQZ2E5mocNY7iFRe9MfBtjurmLYWc OvOSuy1NGY/JYN9+esm
MRfdfVMxbNuPH1ULa7zFC NsBxV2SDDqYHCgqcOx/E0V84Cm2HI2yHD6HiVzK
I7T qxJY/468+pCX2WkMiiKcLB8aJTMoKizHjl08tRAYvj44c En1UAqo8/wHRT76un
n7Og9TgiU0tzAkPYxYT8aSIwn DG1YzlaUWU0I2B00vemMAiBlWG9lvMryvKY4H
1jv MuOdYqyhuHRRmZe2bJ8tLGuMIVqeK6x+FnAng6yZr bC6o3DG3K42VNn/n3A
zewOxK9FGSt4wSgAAAABJR U5ErkJggg== 

Sample Response

Inquire Invoice service returns the response in JSON format.

The returned response contains the following details:

  • merchantID
  • authenticationToken
  • An array of invoices details for the requested invoices
{
	"amount":"1000", " cardType":"visa",
	"paymentLink":"http://localhost:908l/URLShortener?t=a2kBfa",
	"type":"Pre-Auth & Completion",
	"completionCurrency":"840",
	"authenticationToken":"YTlzYzBhZmU50TI2MTU3Z6M5ZjgzYml5”, "rrn":"118811324895", authorizedCurrency": "840",
	"qrCode":"iVBORw0KGgoAAAANSUhEUgAAA3YAAACWAQAAAAAUekxPAAABGElEQVR42u2WMa/ONAiE2fjlbLDxlxmeS		HI4qdTXLeexVqTgllJDufOlsr7Wn/wYy03Ey0vXSpQ0S2xMwlei5FlolnhoKcojLMzQ+DGGdvMU66tRiX705SinDMLnXh25P2V5A/331jIUols/VkzWnGdwIA5W0TtcMGDY7k/70NtH9PRjWbjRxPDMvplnleZHxpE7/LGtoM9N*E2xEs0ANsGBxmpUI4iEQOnnPgGAJyZuZz5GhWUyzuHuXSbPcldavaI9fGlGsS3gHsfOeAcMKh9BgZC6UZldC7FkIZ3aGtfKmlZZLtt3ZyAckD81CJ14Hkt9ZlVkgItb8EBxh3XHNCt44»INg4e6HIMuPZaNR78ZpjyLLff8LD7AXIvM0CX)QZRDgAAAAB3RU5Erk3ggg==",
	"merchantlD":"Merchant",
	"completionAmount":"1000",
	"authorizedAmount":"71",
	"invoicelD":"30231175”,
	"currency”:"840",
	"refundCurrency": "840",
	"invoiceStatus":"REFUNDED",
	"expiryDatelime":"10-07-2021 08:29:20",
	"cardNumber" : "401200"**"“ 0026",
	"refundAmount":"1000"
}

Sample Code

import java.io.BufferedReader; 
import java.io.InputStreamReader; 
import java.io.OutputStreamWriter; 
import java.net.URL; 
import java.net.URLConnection; 
. 
. 
. 
 
// Prepare the invoice 
String authenticationToken="N2FiZDRmYTQzNDUzOGM0YTI4N2I5YmZm"; 
String merchantId="testMerchant"; 
 
// Create Invoice Object and putting merhantID,authenticationToken,invoiceID in it 
 
JSONObject invoice = new JSONObject(); 
invoice.put("invoicID","852355"); 
invoice.put("authenticationToken",authenticationToken); 
invoice.put("merchantID",merchantId); 
 
// Now we have the Parameter Ready we need to send ther request  
 
StringBuilder querySB= new StringBuilder("invoice=").append(invoice.toString()); 
 
URL url = new URL("http://SMARTLINK_DOMAIN/URL2PayAdminWeb/rest/InvoicesService/createInvoice"); 
URLConnection conn = url.openConnection(); 
conn.setConnectTimeout(200000); 
conn.setReadTimeout(200000); 
conn.setDoOutput(true); 
OutputStreamWriter writer = new OutputStreamWriter(conn.getOutputStream(), "UTF-8"); 
// Write parameters 
writer.write(querySB.toString()); 
writer.flush(); 
// Get the response 
StringBuffer output = new StringBuffer(); 
BufferedReader reader = new BufferedReader(new InputStreamReader(conn.getInputStream())); 
 
String line; 
while ((line = reader.readLine()) != null) { 
  output.append(line); 
} 
writer.close(); 
reader.close(); 
 
//Output the response 
System.out.println("response"+output.toString()); 

What's Next