Create an invoice

Creating an invoice

Now that an access token has been provided, we are now able to create invoices in the N-Genius Online gateway. To accept a payment from a customer, an order is always required so that we have something to interact with in all our API interactions with the gateway, and on the Portal user interface.

HTTP Request Method: POST
Resource (URI): https://api-gateway.sandbox.ngenius-payments.com/invoices/outlets/[your-outlet-reference]/invoice

Headers:

Add these headers to your request (note that you should replace 'access_token' with the access token value we received from the Obtain an access token step).

Header	Value
Authorization	Bearer access_token
Content-Type	application/vnd.ni-invoice.v1+json

Body:

Add the following JSON information to the form/body content of your request.

Parameter	Description	Example value
firstName	recipient first name	Test
lastName	recipient last name	Customer
email	recipient email address	[email protected]
transactionType	Type (action) of transaction	PURCHASE
emailSubject	Email Subject	Payment Request
invoiceExpiryDate	Expiry date of invoice link	2019-07-28
paymentAttempts	`(optional)` How many times can your customer attempt payment?	3
redirectUrl	`(optional)` What URL will your customer be redirected to after payment?	https://yoursite.com/yourscript
items [ ]	Array of items	N/A
items.[x].description	Item description	1 x large widget
items.[x].totalPrice { }	Item block	N/A
items.[x].totalPrice.currencyCode	Item currency	AED
items.[x].totalPrice.value	Item amount / price	100
items.[x].quantity	Item quantity	1
total { }	Total block
total.currencyCode	Total currency	AED
total.value	Total amount / price	100
message	Recipient message	Your message

Note: these are the mandatory minimum input parameters for creating an invoice using the N-Genius Online gateway APIs - more values are available.

Example request (body):

{
      "firstName":"Test",
      "lastName":"Customer",
      "email":"[email protected]",
      "transactionType":"PURCHASE",
      "emailSubject": "Invoice from ACME Services LLC",
      "invoiceExpiryDate": "2019-07-28",
      "items":[
        {
          "description":"1 x large widget",
          "totalPrice":{
            "currencyCode":"AED",
            "value":100
          },
          "quantity": 1
        }
      ],
      "total":{
        "currencyCode":"AED",
        "value":100
      },
      "message":"Thank you for shopping with ACME Services LLC. Please visit the link 									provided below to pay your bill. We will ship your order once we have 									confirmation of your payment."
    }

Example response (body):

{
    "_links": {
        "self": {
            "href": "https://<<apiSandboxDomain>>/invoices/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/invoice/abdc4f7e-9b4d-42ef-bccc-7674056d0f0a"
        },
        "payment": {
            "href": "https://<<apiSandboxDomain>>/invoices/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/invoice/abdc4f7e-9b4d-42ef-bccc-7674056d0f0a/payment"
        },
        "email-data": {
            "href": "https://<<apiSandboxDomain>>/invoices/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/invoice/abdc4f7e-9b4d-42ef-bccc-7674056d0f0a/email-data"
        },
        "resend": {
            "href": "https://<<apiSandboxDomain>>/invoices/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/invoice/abdc4f7e-9b4d-42ef-bccc-7674056d0f0a/resend"
        }
    },
    "emailSubject": "Invoice from ACME Services LLC",
    "invoiceExpiryDate": "2019-07-28",
    "locale": "en_US",
    "reference": "abdc4f7e-9b4d-42ef-bccc-7674056d0f0a",
    "outletRef": "5edab6d7-5946-43f4-b8c7-06b29c272bdd",
    "orderReference": "c94195da-5d8f-4435-87d6-f3771fa0a529",
    "firstName": "Test",
    "lastName": "Customer",
    "email": "[email protected]",
    "transactionType": "PURCHASE",
    "items": [
        {
            "description": "1 x large widget",
            "totalPrice": {
                "currencyCode": "AED",
                "value": 100
            },
            "quantity": 1
        }
    ],
    "total": {
        "currencyCode": "AED",
        "value": 100
    },
    "message": "Thank you for shopping with ACME Services LLC. Please visit the link provided below to pay your bill. We will ship your order once we have confirmation of your payment."
}