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
skipInvoiceCreatedEmailNotification	`(optional)` Skip sending the email notification to customer	true/false (default value: false)

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

Retrieve the Invoice Payment Link

Once an invoice is successfully created, you will receive a payment link in the response body. This link is essential, as it redirects the customer to the hosted payment page for completing the transaction.

The link is found in the response at:

_links.payment.href

For example:

"payment":  {  "href":  "https://paypage.sandbox.ngenius-payments.com/invoices/invoice/5ba6d877-1a90-49e3-acef-a31c9cc4ec35/payment"  }

You can now:

Share this URL with your customer directly, OR
Trigger an email notification from the next step if you’ve enabled that feature.

📘
☝️ Note: This is the actual Pay-by-Link your customer uses to pay the invoice. It’s secure, hosted, and fully managed by N-Genius Online.

Creating an invoice

Headers:

Body:

Example request (body):

Example response (body):

Retrieve the Invoice Payment Link

📘☝️ Note: This is the actual Pay-by-Link your customer uses to pay the invoice. It’s secure, hosted, and fully managed by N-Genius Online.

📘
☝️ Note: This is the actual Pay-by-Link your customer uses to pay the invoice. It’s secure, hosted, and fully managed by N-Genius Online.