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 Header | Description |
---|---|
Content-Type | supported content type is application/json |
Authorization | Http basic Auth is Base 64 encoded and formatted as follows: Basic Base64(api_user:api_password) |
x-api-key | Your application token |
mode | Live 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 :
Parameter | Mandatory | Description |
---|---|---|
client_name | Yes | The name of the client. This is the name that will be displayed in the invoice. |
client_email | Yes | The email address of the client. This is the email address where the invoice will be sent. |
client_phone_number | Yes | The phone number of the client. This is the phone number that will be displayed in the invoice. |
due_date | Yes | The due date of the invoice. This is the date after which the invoice will be considered as overdue. |
partial_payment | Yes | The partial payment status of the invoice. This is the status that determines whether the invoice can be partially paid or not. |
type | Yes | The type of the invoice. This is the type that determines whether the invoice is a NORMAL invoice or an INSTALLMENT invoice. |
currency | Yes | The currency of the invoice. This is the currency that will be used to display the amounts in the invoice. |
items | Yes | The list of various products of the invoice. These are the products that will be displayed in the invoice. |
installments | Yes | The 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
}
}
}
Parameter | Description |
---|---|
status | The transaction status. |
statusCode | The Transaction status code |
message | The API return message. |
data | Data returned by the API |
link | The invoice link |
The invoice payment link generated is valid untill the invoice is paid.
Last updated on March 3, 2025