Close
    logo

    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 In case you are still in development phase, you will need to call our API using the following testing endpoint API point URL


    EndpointValue
    URLhttps://test-api.kashier.io/paymentRequest?currency=EGP
    Methodpost

    Meanwhile, whenever you are ready for production, you should use the following production API endpoint URL instead


    Parameters

    ParameterTypeDescriptionRequired
    currencyQuery ParameterCurrency in which price is set. Allowed values are: EGP , EUR , GBP , USDTrue

    Headers

    KeyDescription
    Content-TypeThe content header is just information about the type of returned data.
    AuthorizationThe 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 shrink
    1curl -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 shrink
    1{
    2 "paymentType": "professional",
    3 "merchantId": "MID-3552-454",
    4 "isSuspendedPayment":true,
    5 "customerName": "test customer",
    6 "description": "some description",
    7 "dueDate": "2021-06-01",
    8 "totalAmount":200,
    9 "invoiceReferenceId": "620",
    10 "invoiceItems": [
    11 {
    12 "description": "invoice item description",
    13 "quantity": 5,
    14 "itemName": "laptop",
    15 "unitPrice": 10,
    16 "subTotal": 50
    17 }
    18 ],
    19 "state": "submitted",
    20 "extraFees": [
    21 {
    22 "name": "xxx",
    23 "rate": 100,
    24 "flatFee": 100
    25 }
    26 ],
    27 "tax": 0
    28}

    Body description

    ParameterDescription
    paymentTypeThis 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.
    merchantIdMerchant account number or merchant ID
    totalAmountPayment request amount. Only useful if list items and tax values are ignored you can remove it if paymentType is professional.
    customerNameName of your customer who will recieve a Invoice
    isSuspendedPaymentWhen isSuspendedPayment's value is true, the invoice will be closed after the due date, regardless of whether it has been paid or unpaid
    descriptionA short description of the payment request
    invoiceItemsArray of items into the format [{"itemName":"item 1", "unitPrice":10 , "quantity":"5" , "subTotal":"50" }]
    extraFeesArray of items into the format [{"name":"name of fee", "rate":10 , "flatFee":"5" }] The rate represents the percentage of order cost (%) and flatFee represents the additional fee
    invoiceReferenceIdNumeric value of invoice. Every invoice should have unique invoiceReferenceId at the merchant level. It is required in case of invoice.
    dueDateISO 8601 with UTC time representation of request due date
    If the due date has been expired, the invoice will expire and cannot be paid if isSuspendedPayment is true

    Response structure

    Click here to expandClick here to shrink
    1{
    2 "response": {
    3 "paymentStatus": "unpaid",
    4 "dueDate": "2023-08-16T10:49:24.831Z",
    5 "isSuspendedPayment": true,
    6 "currency": "EGP",
    7 "isBulkCreated": false,
    8 "_id": "64db72328de66500137346a8",
    9 "merchantId": "MID-3552-454",
    10 "autoGeneratedId": 458,
    11 "invoiceReferenceId": "258.468",
    12 "paymentType": "professional",
    13 "totalAmount": 200,
    14 "availableAmountForRefund": 200,
    15 "description": "some description",
    16 "state": "submitted",
    17 "invoiceItems": [
    18 {
    19 "_id": "64db72328de66500137346a9",
    20 "description": "invoice item description",
    21 "quantity": 5,
    22 "itemName": "laptop",
    23 "unitPrice": 10,
    24 "subTotal": 50
    25 }
    26 ],
    27 "customerName": "test customer",
    28 "paymentRequestId": "INV-3552454554",
    29 "creationDate": "2023-08-15T12:40:18.130Z",
    30 "merchantInfo": {
    31 "storeName": "TEST ft- MK Co"
    32 },
    33 "createdByUserId": "5feccc49043fa4001f599657",
    34 "extraFees": [
    35 {
    36 "name": "xxx",
    37 "rate": 100,
    38 "flatFee": 100
    39 }
    40 ],
    41 "channel": "web",
    42 "deviceType": "PostmanRuntime/7.29.3",
    43 "transactions": [],
    44 "__v": 0
    45 },
    46 "messages": {
    47 "en": "Invoice saved",
    48 "ar": "تم حفظ الفاتورة"
    49 },
    50 "status": "SUCCESS"
    51}

    Get Invoice's URL

    get invoice's url to share it with your customers In case you are still in development phase, you will need to call our API using the following testing endpoint API point URL



    Meanwhile, whenever you are ready for production, you should use the following production API endpoint URL instead


    Parameters

    ParameterTypeDescriptionRequired
    paymentRequestIdPath ParameterThe invoice objectId or INV- you want to editTrue
    modeQuery ParameterThe operation you want in this case is test or liveTrue

    View Invoice

    Get details of an invoice on your integration.


    In case you are still in development phase, you will need to call our API using the following testing endpoint API point URL



    Meanwhile, whenever you are ready for production, you should use the following production API endpoint URL instead

    Parameters

    ParameterTypeDescription
    paymentRequestId_or_idPath ParameterThe invoice objectId or INV- you want to fetch

    Headers

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

    Click here to shrink
    1curl -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 shrink
    1{
    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.



    Meanwhile, whenever you are ready for production, you should use the following production API endpoint URL instead


    Parameters

    ParameterTypeDescriptionRequired
    MIDPath ParameterMerchant account number or merchant IDTrue
    currencyPath QueryFilter by currencyTrue
    paymentStatusPath Querypayment status [paid,unpaid]False
    startDatePath QueryA timestamp from which to start listing invoice e.g. 2021-04-07T00:00:05.000Z,2021-04-07False
    endDatePath QueryA timestamp from which to stop listing invoice e.g. 2021-04-07T00:00:05.000Z,2021-04-07False
    startDueDatePath QueryFilter by Due Date which to start listing invoice e.g. 2021-04-07T00:00:05.000Z,2021-04-07False
    endDueDatePath QueryFilter by Due Date which to stop listing invoice e.g. 2021-04-07T00:00:05.000Z,2021-04-07False
    startAmountRangePath QueryFilter by Amount ID which to start listing invoiceFalse
    endAmountRangePath QueryFilter by Amount ID which to stop listing invoice IDFalse
    summaryPath QueryFilter by Summary IDFalse
    currentPagePath QuerySpecify exactly what invoice you want to page. If not specify we use a default value of 1False
    pageSizePath QuerySpecify how many records you want to retrieve per page. If not specify we use a default value of 500.False

    Headers

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

    Click here to shrink
    1curl -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 shrink
    1{
    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.



    Meanwhile, whenever you are ready for production, you should use the following production API endpoint URL instead



    Headers

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

    Click here to shrink
    1curl -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 shrink
    1{
    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

    ParameterDescription
    operationOperation is either via email or phone
    customerEmailCustomer email which is used to share invoice's link
    customerPhoneNumberCustomer phone number which is used to share invoice's link
    customerNameName of your customer who will recieve a Invoice
    subDomainUrlShould be http://merchant.kashier.io/en/prepay
    urlIdentifierInvoice or Payment Request identifier INV-

    Response structure

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

    Update Invoice

    Mark invoice as paid or cancel invoice on your integration



    Meanwhile, whenever you are ready for production, you should use the following production API endpoint URL instead

    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

    ParameterTypeDescriptionRequired
    MIDPath ParameterMerchant account number or merchant IDTrue
    paymentRequestIdPath ParameterThe invoice objectId or INV- you want to editTrue
    operationQuery ParameterThe operation you want in this case is editTrue
    currencyQuery ParameterCurrency in which price is set. Allowed values are: EGP , EUR , GBP , USDTrue

    Headers

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

    Click here to shrink
    1curl -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 shrink
    1{
    2 "operation": "changestatus",
    3 "paymentType": "professional",
    4 "paymentStatus": "paid",
    5 "state": "cancelled"
    6}

    Body description

    ParameterDescription
    operationThe operation you want in this case is change status for paid/cancel invoice
    paymentTypeThis 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.
    paymentStatusMarking Invoice/Payment Request as paid this value must be paid
    stateChanging 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 shrink
    1{
    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.



    Meanwhile, whenever you are ready for production, you should use the following production API endpoint URL instead

    Parameters

    ParameterTypeDescriptionRequired
    MIDPath ParameterMerchant account number or merchant IDTrue
    paymentRequestIdPath ParameterThe invoice objectId or INV- you want to deleteTrue

    Headers

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

    Click here to shrink
    1curl -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 shrink
    1{
    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}

    Add Webhook

    Kashier uses webhook to notify your application when an payment and refund event happens in your account.



    Meanwhile, whenever you are ready for production, you should use the following production API endpoint URL instead

    Parameters

    ParameterTypeDescriptionRequired
    actionQuery Parameterthe action you want in this case is webhookTrue
    operationQuery ParameterThe operation you want in this case is updatemerchantuserTrue

    Headers

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

    Click here to shrink
    1curl -X 'PUT' 'https://test-api.kashier.io/merchant?action=webhook&operation=updatemerchantuser'
    2-H 'Authorization: your_secretKey'
    3-H 'accept: application/json'
    4-d '{
    5 "MID":"MID-1902-526" ,
    6 "webhookUrl":"https://webhook.com/7a5c4030-a5b1-4233-b9a2-d21ed5c22e63"
    7}'

    Body structure

    Click here to shrink
    1{
    2 "MID":"MID-1902-526" ,
    3 "webhookUrl":"https://webhook.com/7a5c4030-a5b1-4233-b9a2-d21ed5c22e63"
    4}

    Response structure

    Click here to shrink
    1{
    2 "status": 200,
    3 "body": {
    4 "_id": "5f5ddc06e5b69000180ef81c",
    5 "merchantPayformanceId": "MID-1902-526",
    6 "webhook": {
    7 "isEnabled": true,
    8 "_id": "64bfe2a34685e900136d7f94",
    9 "url": "https://webhook.com/7a5c4030-a5b1-4233-b9a2-d21ed5c22e63",
    10 "apiKey": "gV8M2FvsWzyrUic1DlbSmG0thXX88PC8XGj5lc4P8CHVDcEXcIgH7PhoVds7CTbe",
    11 "MID": "MID-1902-526"
    12 }
    13 }
    14}

    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