Invoice
Installment Invoice

Create Installment Invoice

This action allows you to create a new invoice.

Create Invoice API call

Authentication information:

All requests to the Payunit REST API must be authenticated. Payunit supports two forms of authentication, both using HTTP basic authentication, which uses the following username/password schemes:

  • API USER and API PASSWORD
  • Application token

BASE_URL : https://gateway.payunit.net (opens in a new tab)

Http headers : HTTP header specifications for all API calls.

HTTP HeaderDescription
Content-Typesupported content type is application/json
AuthorizationHttp basic Auth is Base 64 encoded and formatted as follows: Basic Base64(api_user:api_password)
x-api-keyYour application token
modeLive or test. Your application's current mode

Request to Create installment Invoice on Payunit

curl --location --request POST '{{base_url}}/api/gateway/invoice/create' \
--header 'x-api-key: live_xxxxxxxxxxxxxxx' \
--header 'mode: live' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic xxxxxxxxxx' \
--data-raw '{
  "client_name": "Brooklyn Perry",
  "client_email": "[email protected]",
  "client_phone_number": "(924) 913-0817",
  "due_date": "2024-05-14T13:53:22.060Z",
  "partial_payment": false,
  "type": "INSTALLMENT",
  "currency": "XAF",
  "items": [
    {
      "name": "recovery",
      "amount": 100000,
      "quantity": 1
    }
  ],
  "installments": [
    {
      "amount": 50000,
      "title": "title 1"
    },
    {
      "amount": 30000,
      "title": "title 2"
    },
    {
      "amount": 20000,
      "title": "title 3"
    }
  ]
}

End point: {BASE_URL}/api/gateway/invoice/create

Request method: POST

⚠️

All URLs must utilize HTTPS protocol { success_url,cancel_url,notify_url,image_url }; otherwise, the requests will not be successful.

Request body :

ParameterMandatoryDescription
client_nameYesThe name of the client. This is the name that will be displayed in the invoice.
client_emailYesThe email address of the client. This is the email address where the invoice will be sent.
client_phone_numberYesThe phone number of the client. This is the phone number that will be displayed in the invoice.
due_dateYesThe due date of the invoice. This is the date after which the invoice will be considered as overdue.
partial_paymentYesThe partial payment status of the invoice. This is the status that determines whether the invoice can be partially paid or not.
typeYesThe type of the invoice. This is the type that determines whether the invoice is a NORMAL invoice or an INSTALLMENT invoice.
currencyYesThe currency of the invoice. This is the currency that will be used to display the amounts in the invoice.
itemsYesThe list of various products of the invoice. These are the products that will be displayed in the invoice.
installmentsYesThe list of installments. This is the list that contains the installments that will be displayed in the invoice.

Response body:

 
{
    "status": "SUCCESS",
    "statusCode": 200,
    "message": "Invoice created",
    "data": {
        "link": "https://d1im41dw2xzw4q.cloudfront.net/invoice/8a84e10d-8b01-4db4-b4e8-a52047d4cf8e",
        "invoice": {
            "ref": "INV-1739884097930",
            "amount_paid": 0,
            "remaining_amount": 100000,
            "status": "UNPAID",
            "client": {
                "uuid": "d2614f47-0fab-4c2d-9a62-eecd59553e54",
                "created_at": "2024-06-06T12:00:16.677Z",
                "lastChangedDateTime": "2024-06-06T12:00:16.677Z",
                "isDeleted": null,
                "name": "Brooklyn Perry",
                "email": "[email protected]",
                "phone_number": "(924) 913-0817"
            },
            "total_amount": 100000,
            "due_date": "2024-05-14T13:53:22.060Z",
            "sub_total": 100000,
            "company": {
                "uuid": "5aae9972-d428-4c65-ab5a-662b6dc39b61",
                "created_at": "2024-06-06T11:44:01.765Z",
                "lastChangedDateTime": "2024-06-06T11:44:01.765Z",
                "isDeleted": null,
                "name": "Edi Fashoion",
                "slug": null,
                "email": "[email protected]",
                "phone_number": "23456734567",
                "logo": "https://payunit-public-assets-staging.s3.us-east-2.amazonaws.com/payunit-invoice/4ffbcc14-fedc-4437-8be6-d7975fbd056a/1717674241164.image/png",
                "user_id": "4ffbcc14-fedc-4437-8be6-d7975fbd056a",
                "application_id": "40dc357d-8f04-4bcf-a511-9207e7cd3156"
            },
            "is_custom_company": false,
            "callback_url": null,
            "type": "INSTALLMENT",
            "partial_payment": false,
            "currency": "XAF",
            "items": [
                {
                    "name": "recovery",
                    "amount": "100000",
                    "quantity": "1",
                    "ref": "ITEM1739884097938",
                    "uuid": "1edc8db6-1d68-4bc3-a304-2c5eb49ed4bd",
                    "created_at": "2025-02-18T13:08:17.938Z",
                    "lastChangedDateTime": "2025-02-18T13:08:17.938Z",
                    "isDeleted": null
                }
            ],
            "fees": null,
            "installments": [
                {
                    "title": "title 1",
                    "amount": 50000,
                    "ref": "INSTALLMENT48098015212828",
                    "status": "PENDING",
                    "due_date": null,
                    "partial_payment": false,
                    "transaction_id": null,
                    "uuid": "b1fe9b18-af5f-4710-bba9-e1a0d462e4b0",
                    "created_at": "2025-02-18T13:08:18.026Z",
                    "lastChangedDateTime": "2025-02-18T13:08:18.026Z",
                    "isDeleted": null
                },
                {
                    "title": "title 2",
                    "amount": 30000,
                    "ref": "INSTALLMENT150894980948004",
                    "status": "PENDING",
                    "due_date": null,
                    "partial_payment": false,
                    "transaction_id": null,
                    "uuid": "0371642a-eaff-413f-a588-e539e6db1c7c",
                    "created_at": "2025-02-18T13:08:18.124Z",
                    "lastChangedDateTime": "2025-02-18T13:08:18.124Z",
                    "isDeleted": null
                },
                {
                    "title": "title 3",
                    "amount": 20000,
                    "ref": "INSTALLMENT162517196181412",
                    "status": "PENDING",
                    "due_date": null,
                    "partial_payment": false,
                    "transaction_id": null,
                    "uuid": "763f66d9-328c-4ea2-9829-957427a2dcec",
                    "created_at": "2025-02-18T13:08:18.124Z",
                    "lastChangedDateTime": "2025-02-18T13:08:18.124Z",
                    "isDeleted": null
                }
            ],
            "custom_billing_company": null,
            "uuid": "8a84e10d-8b01-4db4-b4e8-a52047d4cf8e",
            "created_at": "2025-02-18T13:08:17.930Z",
            "lastChangedDateTime": "2025-02-18T13:08:17.930Z",
            "isDeleted": null
        }
    }
}
ParameterDescription
statusThe transaction status.
statusCodeThe Transaction status code
messageThe API return message.
dataData returned by the API
linkThe invoice link

The invoice payment link generated is valid untill the invoice is paid.

Last updated on March 3, 2025