Invoices

Invoices are statements of amounts owed by a customer, and are either generated one-off, or generated periodically from a subscription.

They contain invoice items, every items contains name, price, quantity

Your invoice is billed by sending an email, then based on your email settings, Kashier will email the invoice to your customer and await payment. These emails can contain a link to a hosted page to pay the invoice.

Create Invoice

Create an invoice for payment on your integration

Endpoint	Value
URL	https://test-api.kashier.io/paymentRequest?currency=EGP
Method	post

Parameters

Parameter	Type	Description	Required
currency	Query Parameter	Currency in which price is set. Allowed values are: EGP , EUR , GBP , USD	True

Headers

Key	Description
Content-Type	The content header is just information about the type of returned data.
Authorization	The Authorization is secretkey that is used to identify the merchant , you can obtain from kashier's dashboard, learn more about Authorization.

In case create bulk invoices or PaymentRequests, You should send array of invoices or paymentRequests


Click here to expandClick here to shrink1curl -X 'POST' 'https://test-api.kashier.io/paymentRequest?currency=EGP'
2-H 'Authorization: your_secretKey'
3-H 'Content-Type: application/json'
4-d' {"paymentType": "professional","merchantId" : "MID-3552-454" ,"totalAmount": 50,"customerName": "test customer","description":"some description","invoiceReferenceId": "143484","dueDate": "2021-06-01","invoiceItems": [{"description": "invoice item description","quantity": 5,"itemName": "laptop","unitPrice": 10,"subTotal": 50}],"state": "submitted","tax": 0}'

Body structure


Click here to expandClick here to shrink1{
2  "paymentType": "professional",
3  "merchantId": "MID-3552-454",
4  "totalAmount": 50,
5  "customerName": "test customer",
6  "description": "some description",
7  "dueDate": "2021-06-01",
8  "invoiceReferenceId": "620",
9  "invoiceItems": [
10    {
11      "description": "invoice item description",
12      "quantity": 5,
13      "itemName": "laptop",
14      "unitPrice": 10,
15      "subTotal": 50
16    }
17  ],
18  "state": "submitted",
19  "tax": 0
20}

Body description

Parameter	Description
paymentType	This enum for identify created object type payment request or invoice or order if you need create payment request = simple, if you need create invoice = professional, if you need create order = order.
merchantId	Merchant account number or merchant ID
totalAmount	Payment request amount. Only useful if list items and tax values are ignored.
customerName	Name of your customer who will recieve a Invoice
description	A short description of the payment request
invoiceItems	Array of items into the format `[{"itemName":"item 1", "unitPrice":10 , "quantity":"5" , "subTotal":"50" }]`
invoiceReferenceId	Numeric value of invoice. Every invoice should have unique invoiceReferenceId at the merchant level. It is required in case of invoice.
dueDate	ISO 8601 representation of request due date

Response structure


Click here to expandClick here to shrink1{
2  "response": {
3    "paymentStatus": "unpaid",
4    "currency": "EGP",
5    "_id": "606dc41e37affc0018d26370",
6    "merchantId": "MID-3552-454",
7    "autoGeneratedId": 184,
8    "invoiceReferenceId": "1434984",
9    "paymentType": "professional",
10    "totalAmount": 50,
11    "availableAmountForRefund": 50,
12    "description": "some description",
13    "state": "submitted",
14    "dueDate": "2021-06-01T00:00:00.000Z",
15    "invoiceItems": [
16      {
17        "_id": "606dc41e37affc0018d26371",
18        "description": "invoice item description",
19        "quantity": 5,
20        "itemName": "laptop",
21        "unitPrice": 10,
22        "subTotal": 50
23      }
24    ],
25    "customerName": "test customer",
26    "paymentRequestId": "INV-3552454160",
27    "tax": 0,
28    "creationDate": "2021-04-07T14:39:26.389Z",
29    "merchantInfo": {
30      "storeName": "MK Company"
31    },
32    "createdByUserId": "5feccc49043fa4001f599657",
33    "transactions": [],
34    "__v": 0
35  },
36  "messages": {
37    "en": "Payment request saved",
38    "ar": "Payment request saved"
39  },
40  "status": "SUCCESS"
41}

View Invoice

Get details of an invoice on your integration.

Endpoint	Value
URL	https://test-api.kashier.io/paymentRequest/:paymentRequestId_or_id
Method	get

Parameters

Parameter	Type	Description
paymentRequestId_or_id	Path Parameter	The invoice objectId or INV- you want to fetch

Headers

Key	Description
Authorization	The Authorization is secretkey that is used to identify the merchant , you can obtain from kashier's dashboard, learn more about Authorization.


Click here to expandClick here to shrink1curl -X 'GET' 'https://test-api.kashier.io/paymentRequest/:paymentRequestId_or_id'
2-H 'Authorization: your_secretKey'
3-H "accept: application/json"

Response structure


Click here to expandClick here to shrink1{
2  "response": {
3    "data": [
4      {
5        "merchantInfo": {
6          "storeName": "MK Company"
7        },
8        "paymentStatus": "unpaid",
9        "currency": "EGP",
10        "_id": "606dc41e37affc0018d26370",
11        "merchantId": "MID-3552-454",
12        "autoGeneratedId": 184,
13        "invoiceReferenceId": "1434984",
14        "paymentType": "professional",
15        "totalAmount": 50,
16        "availableAmountForRefund": 50,
17        "description": "some description",
18        "state": "submitted",
19        "dueDate": "2021-06-01T00:00:00.000Z",
20        "invoiceItems": [
21          {
22            "_id": "606dc41e37affc0018d26371",
23            "description": "invoice item description",
24            "quantity": 5,
25            "itemName": "laptop",
26            "unitPrice": 10,
27            "subTotal": 50
28          }
29        ],
30        "customerName": "test customer",
31        "paymentRequestId": "INV-3552454160",
32        "tax": 0,
33        "creationDate": "2021-04-07T14:39:26.389Z",
34        "createdByUserId": "5feccc49043fa4001f599657",
35        "transactions": []
36      }
37    ]
38  },
39  "messages": {
40    "en": "The Payment Requests have been retrieved [success]",
41    "ar": "The Payment Requests have been retrieved [success]"
42  },
43  "status": "SUCCESS"
44}

List Invoices

List the invoice available on your integration.

Endpoint	Value
URL	https://test-api.kashier.io/paymentRequest/:MID?currency=EGP
Method	get

Parameters

Parameter	Type	Description	Required
MID	Path Parameter	Merchant account number or merchant ID	True
currency	Path Query	Filter by currency	True
paymentStatus	Path Query	payment status [paid,unpaid]	False
startDate	Path Query	A timestamp from which to start listing invoice e.g. `2021-04-07T00:00:05.000Z`,`2021-04-07`	False
endDate	Path Query	A timestamp from which to stop listing invoice e.g. `2021-04-07T00:00:05.000Z`,`2021-04-07`	False
startDueDate	Path Query	Filter by Due Date which to start listing invoice e.g. `2021-04-07T00:00:05.000Z`,`2021-04-07`	False
endDueDate	Path Query	Filter by Due Date which to stop listing invoice e.g. `2021-04-07T00:00:05.000Z`,`2021-04-07`	False
startAmountRange	Path Query	Filter by Amount ID which to start listing invoice	False
endAmountRange	Path Query	Filter by Amount ID which to stop listing invoice ID	False
summary	Path Query	Filter by Summary ID	False
currentPage	Path Query	Specify exactly what invoice you want to page. If not specify we use a default value of 1	False
pageSize	Path Query	Specify how many records you want to retrieve per page. If not specify we use a default value of 500.	False

Headers

Key	Description
Authorization	The Authorization is secretkey that is used to identify the merchant , you can obtain from kashier's dashboard, learn more about Authorization.


Click here to expandClick here to shrink1curl -X 'GET' 'https://test-api.kashier.io/paymentRequests/:MID?currency=EGP'
2-H 'Authorization: your_secretKey'
3-H "accept: application/json"

Response structure


Click here to expandClick here to shrink1{
2    "response": {
3        "data": [
4            {
5                "termsAndConditions": {
6                    "time": "2021-04-05T16:38:02.416Z",
7                    "ip": "196.156.15.116",
8                    "userAgent": {
9                        "chrome": true,
10                        "version": "89.0.4389.114",
11                        "webkit": true
12                    }
13                },
14                "merchantInfo": {
15                    "storeName": "MK Company"
16                },
17                },
18                "paymentStatus": "unpaid",
19                "currency": "EGP",
20                "_id": "606dc41e37affc0018d26370",
21                "merchantId": "MID-3552-454",
22                "autoGeneratedId": 184,
23                "invoiceReferenceId": "1434984",
24                "paymentType": "professional",
25                "totalAmount": 50,
26                "availableAmountForRefund": 50,
27                "description": "some description",
28                "state": "submitted",
29                "dueDate": "2021-06-01T00:00:00.000Z",
30                "invoiceItems": [
31                    {
32                        "_id": "606dc41e37affc0018d26371",
33                        "description": "invoice item description",
34                        "quantity": 5,
35                        "itemName": "laptop",
36                        "unitPrice": 10,
37                        "subTotal": 50
38                    }
39                ],
40                "customerName": "test customer",
41                "paymentRequestId": "INV-3552454160",
42                "tax": 0,
43                "creationDate": "2021-04-07T14:39:26.389Z",
44                "createdByUserId": "5feccc49043fa4001f599657",
45                "transactions": []
46            },
47        ]
48        "pagination": {
49            "totalDocs": 153,
50            "limit": 100000000,
51            "totalPages": 1,
52            "page": 1,
53            "pagingCounter": 1,
54            "hasPrevPage": false,
55            "hasNextPage": false,
56            "prevPage": null,
57            "nextPage": null
58        }
59      },
60    "messages": {
61        "en": "The Payment Requests have been retrieved [success]",
62        "ar": "The Payment Requests have been retrieved [success]"
63    },
64    "status": "SUCCESS"
65}
66

Share Invoice

Send message of an invoice to your customers by email or phone.

Endpoint	Value
URL	https://test-api.kashier.io/paymentRequest/sendInvoiceBy
Method	post

Headers

Key	Description
Authorization	The Authorization is secretkey that is used to identify the merchant , you can obtain from kashier's dashboard, learn more about Authorization.


Click here to expandClick here to shrink1curl -X 'POST' 'https://test-api.kashier.io/paymentRequest/sendInvoiceBy'
2-H 'Authorization: your_secretKey'
3-H 'Content-Type: application/json'
4-d' {"operation": "email","customerEmail": "email@example.com", "customerPhoneNumber": "+201000000000", "customerName": "Mohamed khaled","subDomainUrl": "http://merchant.kashier.io/en/prepay","urlIdentifier": "INV-3552454160"}'

Body structure


Click here to expandClick here to shrink1{
2  "operation": "email",
3  "customerEmail": "email@example.com",
4  "customerPhoneNumber": "+201000000000",
5  "customerName": "Mohamed Khaled",
6  "subDomainUrl": "http://merchant.kashier.io/en/prepay",
7  "urlIdentifier": "INV-3552454160"
8}

Body descriptions

Parameter	Description
operation	Operation is either via email or phone
customerEmail	Customer email which is used to share invoice's link
customerPhoneNumber	Customer phone number which is used to share invoice's link
customerName	Name of your customer who will recieve a Invoice
subDomainUrl	Should be http://merchant.kashier.io/en/prepay
urlIdentifier	Invoice or Payment Request identifier `INV-`

Response structure


Click here to expandClick here to shrink1{
2  "status": "SUCCESS",
3  "message": "Payment link sms sent succesfully"
4}

Update Invoice

Mark invoice as paid or cancel invoice on your integration

Endpoint	Value
URL	https://test-api.kashier.io/paymentRequest/:MID/:paymentRequestId/?currency=EGP&operation=edit
Method	put

This endpoint is used to pay invoice in cash or cancel this invoice depending on model attributes (paymentStatus,state), you can't use them both in the same request.

Parameters

Parameter	Type	Description	Required
MID	Path Parameter	Merchant account number or merchant ID	True
paymentRequestId	Path Parameter	The invoice objectId or INV- you want to edit	True
operation	Query Parameter	The operation you want in this case is edit	True
currency	Query Parameter	Currency in which price is set. Allowed values are: EGP , EUR , GBP , USD	True

Headers

Key	Description
Authorization	The Authorization is secretkey that is used to identify the merchant , you can obtain from kashier's dashboard, learn more about Authorization.


Click here to expandClick here to shrink1curl -X 'PUT' 'https://test-api.kashier.io/paymentRequest/:MID/:paymentRequestId/?operation=edit&currency=EGP'
2-H 'Authorization: your_secretKey'
3-H 'accept: application/json'
4-H 'Content-Type: application/json'
5-d '{"operation": "changestatus","paymentType": "professional","paymentStatus": "paid", "state": "cancelled"}'

Body structure


Click here to expandClick here to shrink1{
2  "operation": "changestatus",
3  "paymentType": "professional",
4  "paymentStatus": "paid",
5  "state": "cancelled"
6}

Body description

Parameter	Description
operation	The operation you want in this case is change status for paid/cancel invoice
paymentType	This enum for identify created object type payment request or invoice or order if you need create payment request = simple, if you need create invoice = professional, if you need create order = order.
paymentStatus	Marking Invoice/Payment Request as paid this value must be paid
state	Changing the state of Invoices/Payment Request to cancelled this value must be cancelled Name of your customer who will recieve a Invoice

Response structure


Click here to expandClick here to shrink1{
2  "response": {
3    "merchantId": "MID-3552-454",
4    "paymentRequestId": "INV-3552454160"
5  },
6  "messages": {
7    "en": "Operation performed successfully",
8    "ar": "العملية تمت بنجاح"
9  },
10  "status": "SUCCESS"
11}

Delete Invoice

Permanently deletes a one-off invoice draft. This cannot be undone. Attempts to delete invoices that are no longer in a draft state will fail. so Payment request Should have {'paymentStatus': 'unpaid'} to be deleted and Invoice Should have {'state': 'draft','paymentStatus': 'unpaid'} to be deleted.

Endpoint	Value
URL	https://test-api.kashier.io/paymentRequest/:MID/:paymentRequestId
Method	delete

Parameters

Parameter	Type	Description	Required
MID	Path Parameter	Merchant account number or merchant ID	True
paymentRequestId	Path Parameter	The invoice objectId or INV- you want to delete	True

Headers

Key	Description
Authorization	The Authorization is secretkey that is used to identify the merchant , you can obtain from kashier's dashboard, learn more about Authorization.


Click here to expandClick here to shrink1curl -X 'DELETE' 'https://test-api.kashier.io/paymentRequest/:MID/:paymentRequestId'
2-H 'Authorization: your_secretKey'
3-H 'accept: application/json'

Response structure


Click here to expandClick here to shrink1{
2  "response": {
3    "data": [
4      {
5        "merchantInfo": {
6          "storeName": "MK Company"
7        },
8        "paymentStatus": "unpaid",
9        "currency": "EGP",
10        "_id": "606dc41e37affc0018d26370",
11        "merchantId": "MID-3552-454",
12        "autoGeneratedId": 184,
13        "invoiceReferenceId": "1434984",
14        "paymentType": "professional",
15        "totalAmount": 50,
16        "availableAmountForRefund": 50,
17        "description": "some description",
18        "state": "draft",
19        "dueDate": "2021-06-01T00:00:00.000Z",
20        "invoiceItems": [
21          {
22            "_id": "606dc41e37affc0018d26371",
23            "description": "invoice item description",
24            "quantity": 5,
25            "itemName": "laptop",
26            "unitPrice": 10,
27            "subTotal": 50
28          }
29        ],
30        "customerName": "test customer",
31        "paymentRequestId": "INV-3552454160",
32        "tax": 0,
33        "creationDate": "2021-04-07T14:39:26.389Z",
34        "createdByUserId": "5feccc49043fa4001f599657",
35        "transactions": []
36      }
37    ]
38  },
39  "messages": {
40    "en": "The Payment Request has been deleted [success]",
41    "ar": "The Payment Request has been deleted [success]"
42  },
43  "status": "SUCCESS"
44}

Invoices Postman Collection

Kashier provides Postman Collections to help you understand and test the API endpoints.

Link Invoices and Payment Request to PaymentUI

Iframe

In case of linking the transcation with invoice or payment-Request the value of data-type attribute must be "paymentRequest", data-orderId attribute must be _id of invoice or payment-Request and data-paymentRequestId must be invoice or payment-Request INV- / PR-

HPP

In case of linking the transcation with invoice or payment-Request the value of type query parameter must be "paymentRequest", orderId query parameter must be _id of invoice or payment-Request and paymentRequestId must be invoice or payment-Request INV- / PR-

Dashboard API — Previous

Authentication

Next — Features

Connected Accounts