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).

HeaderValue
AuthorizationBearer access_token
Content-Typeapplication/vnd.ni-invoice.v1+json

Body:

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

ParameterDescriptionExample value
firstNamerecipient first nameTest
lastNamerecipient last nameCustomer
emailrecipient email address[email protected]
transactionTypeType (action) of transactionPURCHASE
emailSubjectEmail SubjectPayment Request
invoiceExpiryDateExpiry date of invoice link2019-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 itemsN/A
items.[x].descriptionItem description1 x large widget
items.[x].totalPrice { }Item blockN/A
items.[x].totalPrice.currencyCodeItem currencyAED
items.[x].totalPrice.valueItem amount / price100
items.[x].quantityItem quantity1
total { }Total block
total.currencyCodeTotal currencyAED
total.valueTotal amount / price100
messageRecipient messageYour message
skipInvoiceCreatedEmailNotification(optional) Skip sending the email notification to customertrue/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."
}