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. Please consult the X section for a complete list of these parameters.

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