Contents x
Create Invoice
  • 09 Jan 2024
  • 6 Minutes to read
  • Contributors
  • Print
  • Dark
    Light
  • PDF
Contents

Create Invoice

  • Updated on 09 Jan 2024
  • 6 Minutes to read
  • Contributors
  • Print
  • Dark
    Light
  • PDF
Article Summary

Use the Create Invoice web service to generate an invoice using the SmartLink interface. 

Syntax

POST rest/InvoicesService/createInvoice

Service Specifications

Property and Information
  • Endpoint: createInvoice
  • Name: Create 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 for Invoices of type payment: rest/InvoicesService/createInvoice. The path is prefixed with the SmartLink Context root.
  • Path for Invoices of type PreAuth: rest/InvoicesService/createPreAuthInvoice. 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

invoicesDetails
required

Array of JSON Objects contains the details for each invoice. The details of each invoice is described in the below table.

  • Field Type: Array of JSON Objects
  • Length: N/A
  • Sample Data:
    JSON
    "invoicesDetails":[{
"amount":"100",
"customerEmailAddress":"example@payone.io",
"dynamicFields":[{"ItemID":"1"}],
"language":"en",
"expiryperiod":"3D",
"notificationEmail":"example@payone.io",
"paymentDescription":"Sample Payment",
"customerID":"John",
"invoiceID":"30231175",
"currency":"840",
"generateQRCode":"yes",
"customerMobileNumber":"00962797777777",
"notifyMe":"yes"
}]

InvoicesDetails Parameters

ParameterDescription
invoiceID
required		An alphanumeric value that represents the Invoice ID which must be unique per invoice.

  • Field Type: Alphanumeric
  • Length: 60
  • Sample Data: 30231175
amount
required		A numeric value represents the ISO Formatted invoice amount with no decimal point. For example, 100 for 1.00 USD.

  • Field Type: Numeric
  • Length: 9
  • Sample Data: 100
currency
required		A numeric value represents the ISO formatted code of the currency and not the character value. For example, 840 for USD.

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

An alphanumeric value that represents the invoice expiry period and must end with the MI, H, D. MI for Minutes, H for Hours, D for Days. For example, 10D, 2H, 130MI. 

If the value consists of multiple formats, for example, one hour and thirty minutes, it must be converted and sent as 90MI.

  • Field Type: Alphanumeric
  • Length: 9
  • Sample Data: 3D
paymentDescription 
required		An alphanumeric string containing a narrative Payment Description of the invoice, which uses the language specified in the language parameter. This value should be UTF-8 encoded.

  • Field Type: Alphanumeric
  • Length: 255
  • Sample Data: Sample Payment 
customerID
optional 		An alphanumeric string containing a Customer ID that enables the customer to make the payment, save their cards, and use them in the future payment process.

  • Field Type: Alphanumeric
  • Length: 15
  • Sample Data: John
language
optional

  An alphabetic value that represents the interface's language is displayed to the customer and used for the payment description parameter. SmartLink will use this value during the payment process to display the interface. Thus, supporting the selected language to the customer.

For example, Supported values are En, Ar. 

  • Field Type: Alphabetic
  • Length: 2
  • Sample Data: en
notifyMe
optional		This is to provide the merchant with an email notification upon successful payment for the invoice. The email address that will receive the notification will be according to the provided parameter below notificationEmail. If notificationEmail parameter was empty, The notification will be sent to the email address configured in the merchant account.

   Possible values:
  • Yes
  • No
  • Field Type: Alphabetic
  • Length: 3
  • Sample Data: yes
notificationEmail
optional

An alphabetic value that represents the email address on which the Notification Email needs to send.

  • Field Type: Alphanumeric 
  • Length: 100
  • Sample Data: example@payone.io
generateQRCode
optional

This is a flag to generate and provide back a QR Code in Base64 encoding format or NOT.

   Possible values:
  • Yes
  • No
  • Field Type: Alphabetic 
  • Length: 3
  • Sample Data: yes
customerEmailAddress
conditional

An alphabetic value that represents the Customer's Email Address. The customer will receive the Invoice id, Payment link, and other invoice details.

Prerequisite: A proper delivery method of the merchant should be configured at SmartLink. To use this feature, the configuration needs to be enabled and validated. 


  • Field Type: Alphanumeric
  • Length: 60
  • Sample Data: example@payone.io
customerMobileNumber
conditional		A numeric value that represents the Customer's Mobile Number. The customer will receive the Invoice id, Payment link, and other invoice details.

Prerequisite: A proper delivery method of the merchant should be configured at SmartLink. To use this feature, the configuration needs to be enabled and validated.


  • Field Type: Numeric
  • Length: 20
  • Sample Data: 00962797777777
dynamicFields
conditional

JSON Array represents the configured Dynamic Fields for the merchant on SmartLink.

Each dynamic field is a JSON object inside the array. 

  • Field Type: JSONArray
  • Length: -
  • Sample Data: [{“itemID”:”1”}]
generateToken
optional		This flag to indicate whether to generate a Token for the enetred card details or NOT. If this parameter is not passed, then no token will be generated.

This parameter is a part of the tokenization. For more information, see Tokenization.

Possible values:
  • Yes
  • NO  
  • Field Type: Alphabetic 
  • Length: 3
  • Sample Data: Yes
allowedPaymentMethods
optional		This flag to indicate whether to generate a Token for the enetred card details or NOT. If this parameter is not passed, then no token will be generated. This parameter is a string value that signifies a list of permitted payment methods available for this transaction.

Possible Values:
  • VISA
  • MASTERCARD
  • AMEX
  • MADA
  • APPLEPAY
  • GOOGLE_PAY
  • URPAY
  • STCPAY
  • SADAD_BILLING
  • EMKAN
  • TABBY
  • Field Type: String
  • Length: N/A
  • Sample Data: APPLEPAY, URPAY, STCPAY, SADAD_BILLING, EMKAN,     TABBY, GOOGLE_PAY, VISA, MASTERCARD, AMEX, MADA 

Sample Request

Create Invoice service request must contain the details of the invoices you want to create. 

 It is in JSON format and contains the following details:

  • merchantID
  • authenticationToken
  • invoicesDetails
    • amount
    • customerEmailAddress
    • language
    • expiryperiod
    • paymentDescription
    • notificationEmail
    • notifyMe
    • customerID
    • InvoiceID
    • currency
    • generateQRCode
    • CustomerMobileNumber
JSON
invoices={
"merchantID":"maisMerchant",
"authenticationToken":"YTIzYzBhZmU5OTI2MTU3ZGM5ZjgzYmI5",
"invoicesDetails":[{
"amount":"100",
"customerEmailAddress":"example@payone.io",
"dynamicFields":[{"ItemID":"1"}],
"language":"en",
"expiryperiod":"3D",
"notificationEmail":"example@payone.io",
"paymentDescription":"Sample Payment",
"customerID":"John",
"invoiceID":"30231175",
"currency":"840",
"generateQRCode":"yes",
"customerMobileNumber":"00962797777777",
"notifyMe":"yes"
}]
}

Output Parameters

ParameterDescription
merchantID
required

 Upon successful merchant enrollment, the SmartLink operation team provides the alphanumeric value that represents the Merchant ID.

  • Field Type: Alphanumeric
  • Length: 30
  • Sample Data: maisMerchant
authenticationToken
required

Upon successful merchant enrollment, the SmartLink operation team provides the alphanumeric value that represents the Authentication Token.

  • Field Type: Alphanumeric
  • Length: 255
  • Sample Data: YTIzYzBhZmU5OTI2MTU3ZGM5ZjgzYmI5

invoicesDetails
required

Array of JSON Objects contains the details for each invoice. The details of each invoice is described in the below table.

  • Field Type: Array of JSON Objects
  • Length: N/A
  • Sample Data:
    JSON
    "invoicesDetails":[{
"qrcode":"iVBORw0KGgoAAAANSUhEUgAAAJYAAACWAQAAAAAUekxPAAABGE1EQVR42u2WMa/DMAiE2fjLbLDxlxme5HI4qdTXLeexVqTgL1JDufO1sr7WnwYy0JEy0vXSpQ052xMw1ei5FlolnhokcujLMzQ+DGGdvMU66tRiX705SmDMLnXh25P2V5A/331jIUoLs/VkzWnGdwIA5W0TtcMGDY7k70NtH9PRjwbjRxPDMvp1n1eZHxpE7LGtoM9N+E2xEs0ANsGBxmpUI4iEQODnnPgGAJyZuZz5GhWUyzuHuXSbPcIdavaI9fG1GsS3gHsfOeAcMKh9BgzC6UZ1dCFkIz3aGtfKmIzzLttJZyAckD81CJ14Nkt91Ivkgltb8EBxh3XHNCN4+INg+e6HIMuPZaNR78ZpjyLLff8LD7AXIvM0OOQZRDgAAAABJRU5ErkJggg==",
"customerEmai1Address":"example@payone.io",
"customerID":"John",
"invoiceID":"30231175",
"customerMobi1eNumber":"00962797777777",
"paymentLink":"http://localhost:9081/URLShortener?t=a2kBfa",
"expiryDateTime":"10-07-2021 11:29:20"
}]

InvoicesDetails Parameters

ParameterDescription
paymentLink
required

The URL represents the generated Payment Link through which the customer will process their transactions.

invoiceID
required		An alphanumeric value that represents the Invoice ID which must be unique per invoice. The value is the same as the Invoice ID sent in the request.

  • Field Type: Alphanumeric
  • Length: 60
  • Sample Data: 30231175
customerID
required		An alphanumeric string containing a Customer ID that enables the customer to make the payment, save their cards, and use them in the future payment process.

  • Field Type: Alphanumeric
  • Length: 15
  • Sample Data: John
customerEmailAddress
required

An alphabetic value that represents the Customer's Email Address. The customer will receive the Invoice id, Payment link, and other invoice details. The value is the same as the customerEmailAddress sent in the request.

Prerequisite: A proper delivery method of the merchant should be configured at SmartLink. To use this feature, the configuration needs to be enabled and validated.


  • Field Type: Alphanumeric
  • Length: 60
  • Sample Data: example@payone.io
customerMobileNumber
required		An alphabetic value that represents the Customer's Mobile Number. The customer will receive the Invoice id, Payment link, and other invoice details. The value is the same as the customerMobileNumber sent in the request.

Prerequisite: A proper delivery method of the merchant should be configured at SmartLink. To use this feature, the configuration needs to be enabled and validated.


  • Field Type: Numeric
  • Length: 20
  • Sample Data: 00962797777777
expiryDateTime
required

The date represents the computed expiry date and time based on the expiryperiod parameter sent by the merchant.

The request format will be (dd-MM-yyyy HH:mm:ss).

  • Field Type: Date
  • Length: 9
  • Sample Data: 10-07-2021 11:29:20 
qrCode
conditional

A Base64 encoding format represents the generated payment details through which the customer processes their transactions. 

After sending, “generateQRCode” request as ‘yes’, it will return.

  • Field Type: Alphanumeric
  • Length: -
  • Sample Data:
iVBORw0KGgoAAAANSUhEUgAAAJYAAACWAQAAAAAUekxPAAABGElE
QVR42u2WMa/DMAiE2fjLbLDxlxme5HI4qdTXLeexVqTgL1JDufO1sr7Wn/w
Yy0JEy0vXSpQ0S2xMw1ei5FlolnhoKcojLMzQ+DGGdvMU66tRiX7O5SmDM
LnXh25P2V5A/331jIUoLs/VkzWnGdwIA5W0TtcMGDY7k/70NtH9PRjWbjR
xPDMvp1n1eZHxpE7/LGtoM9N+E2xEs0ANsGBxmpUI4iEQOnnPgGAJyZuZz
5GhWUyzuHuXSbPcIdavaI9fGlGsS3gHsfOeAcMKh9BgzC6UZldC7FkIz3aGt
fKmIzzLttJZyAckD81CJ14Nkt9zIVkgItb8EBxh3XHNCN4+INg+e6HIMuPZaNR
78ZpjyLLff8LD7AXIvM0OOQZRDgAAAABJRU5ErkJggg==

Sample Response

Create Invoice service returns the response in JSON format. 

The returned response contains the following details:

  • merchantID
  • authenticationToken
  • InvoicesDetails
    • InvoiceID
    • expiryDateTime
    • qrCode
    • customerEmailAddress
    • customerID
    • customerMobileNumber
    • paymentLink
JSON
invoices={
"merchantID":"maisMerchant",
"authenticationToken":"YTIzYzBhZmU5OTI2MTU3ZGM5ZjgzYmI5",
"invoicesDetai1s":[{
"qrcode":"iVBORw0KGgoAAAANSUhEUgAAAJYAAACWAQAAAAAUekxPAAABGE1EQVR42u2WMa/DMAiE2fjLbLDxlxme5HI4qdTXLeexVqTgL1JDufO1sr7WnwYy0JEy0vXSpQ052xMw1ei5FlolnhokcujLMzQ+DGGdvMU66tRiX705SmDMLnXh25P2V5A/331jIUoLs/VkzWnGdwIA5W0TtcMGDY7k70NtH9PRjwbjRxPDMvp1n1eZHxpE7LGtoM9N+E2xEs0ANsGBxmpUI4iEQODnnPgGAJyZuZz5GhWUyzuHuXSbPcIdavaI9fG1GsS3gHsfOeAcMKh9BgzC6UZ1dCFkIz3aGtfKmIzzLttJZyAckD81CJ14Nkt91Ivkgltb8EBxh3XHNCN4+INg+e6HIMuPZaNR78ZpjyLLff8LD7AXIvM0OOQZRDgAAAABJRU5ErkJggg==",
"customerEmai1Address":"examp1e@payone.io",
"customerID":"John",
"invoiceID":"30231175",
"customerMobi1eNumber":"00962797777777",
"paymentLink":"http://localhost:9081/URLShortener?t=a2kBfa",
"expiryDateTime":"10-07-2021 11:29:20"
}]
}

Sample Code

Java
import java.io.BufferedReader; 
import java.io.InputStreamReader; 
import java.io.OutputStreamWriter; 
import java.net.URL; 
import java.net.URLConnection; 
import org.json.JSONArray; 
import org.json.JSONObject; 
. 
. 
. 
. 
// Prepare the invoices 
String authenticationToken="N2FiZDRmYTQzNDUzOGM0YTI4N2I5YmZm"; 
String merchantId="testMerchant"; 
 
// Create Invoices Object and putting merhantID,authenticationToken in it 
JSONObject invoicesObject= new JSONObject(); 
invoicesObject.put("authenticationToken",authenticationToken); 
invoicesObject.put("merchantID",merchantId); 
 
// Create Invoices JSON array  
JSONArray invoices = new JSONArray(); 
 
// Creating the first invoice 
JSONObject firstInvoice = new JSONObject(); 
firstInvoice.put("invoiceID","852355"); 
firstInvoice.put("amount","2000"); 
firstInvoice.put("currency","840"); 
firstInvoice.put("expiryperiod","120MI"); 
firstInvoice.put("paymentDescription","Sample Payment"); 
firstInvoice.put("language","en"); 
firstInvoice.put("customerEmailAddress","example@payone.io"); 
firstInvoice.put("customerMobileNumber","000000000"); 
firstInvoice.put("notifyMe","yes"); 
firstInvoice.put("notificationEmail","example@payone.io"); 
 
// Creating dynamic fields array 
JSONArray dynafields= new JSONArray(); 
 
// Crreating and Putting ItemId inside as a dynamic field in the array 
JSONObject itemDynaObjcet = new JSONObject(); 
itemDynaObjcet.put("ItemID", "1"); 
dynafields.put(itemDynaObjcet); 
 
// Putting the the dynamicFields array in the firstInvoice 
firstInvoice.put("dynamicFields", dynafields);
// Putting the firstInvoice inside the invoices Array 
invoices.put(firstInvoice); 
 
invoicesObject.put("invoicesDetails",invoices); 
 
// Now we have the Parameter Ready we need to send ther request  
StringBuilder querySB= new StringBuilder("invoices=").append(invoicesObject.toString()); 
 
// This URL will be provided during the Integration  
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