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