Endpoints: /v1/invoices
HTTP Method: POST
Headers:
Production: https://api.midtrans.com/v1/invoices
Sandbox: https://api.sandbox.midtrans.com/v1/invoices
| Key | Description |
|---|---|
| Authorization | Basic Base64Encode(merchantServerKey:) |
Request Body
{
"order_id": "7950c36a-d267-4f25-bb03-7a82b00z168t",
"invoice_number": "7128c81b-cde5-4c33-8777-4d1d0fcd6377",
"due_date": "2025-08-06 20:03:04 +0700",
"invoice_date": "2025-01-06 20:03:04 +0700",
"customer_details": {
"id": "customer_id",
"name": "merchant A",
"email": "[email protected]",
"phone": "82313123123"
},
"payment_type": "payment_link",
"reference": "reference",
"item_details": [
{
"item_id": "SKU1111",
"description": "midtrans pillow",
"quantity": 1,
"price": 2000
}
],
"notes": "just a notes",
"payment_link": {
"is_custom_expiry": true,
"enabled_payments": [
"bca_va"
],
"credit_card": {
"secure": true,
"type": "authorize",
"bank": "bni",
"whitelist_bins": [
"48111111"
],
"installment": {
"required": true,
"terms": {
"mandiri": [
3
],
"bca": [
3
],
"bni": [
3
],
"bri": [
3
],
"cimb": [
3
],
"maybank": [
3
],
"offline": [
3
]
}
}
},
"bca_va": {
"number": "12345678901",
"free_text": {
"inquiry": [
{
"id": "id inquiry",
"en": "en inquiry"
}
],
"payment": [
{
"id": "id payment",
"en": "en payment"
}
]
}
},
"bni_va": {
"number": "12312312312"
},
"permata_va": {
"number": "12312312312",
"recipient_name": "name"
},
"bri_va": {
"number": "12312312312"
},
"cimb_va": {
"number": "12312312312"
},
"expiry": {
"unit": "months",
"duration": 1,
"start_time": "2025-02-21 09:48:29 +0700"
}
},
"amount": {
"vat": "12313",
"discount": "1000",
"shipping": "11"
}
}
{
"order_id": "7950c36a-d267-4f25-bb03-7a82b00z168t",
"invoice_number": "7128c81b-cde5-4c33-8777-4d1d0fcd6377",
"due_date": "2025-08-06 20:03:04 +0700",
"invoice_date": "2025-01-06 20:03:04 +0700",
"customer_details": {
"id": "customer_id",
"name": "merchant A",
"email": "[email protected]",
"phone": "82313123123"
},
"payment_type": "virtual_account",
"reference": "reference",
"item_details": [
{
"item_id": "SKU1111",
"description": "midtrans pillow",
"quantity": 1,
"price": 2000
}
],
"notes": "just a notes",
"virtual_accounts": [
{
"bank": "bca_va"
}
],
"amount": {
"vat": "12313",
"discount": "1000",
"shipping": "11"
}
}
Request JSON Body Details
| Parameter | Description |
|---|---|
| order_id String (36) Required | Id for the order, must be unique for each invoice NOTE: only consist of alphanumeric characters [a-z, 0-9], hyphens [-], underscores [_], tilde [~] and dot [.] |
| Invoice_number String (40) Required | Number of the invoice |
| Due_date String (40) Required | Due date of transaction in ISO 8601 format. Default time zone: GMT+7 and has to be after invoice_date. For example: 2025-08-06 20:03:04 +0700 |
| Invoice_date String (40) Required | Date of Invoice and will be used in email and PDF created in ISO 8601 format. Default time zone: GMT+7. For example: 2025-08-06 20:03:04 +0700 |
| Customer_details Required | Refer to Customer Details object section. |
| Reference String(90): Optional | Reference of the invoice |
| Item_details Array: Required (Min 1) | Refer to Item Detail object section (NOTE: total price must not be 0) |
| Notes String(1000): Optional | Notes of the invoice |
| Payment_type String: Required | Either payment_link or virtual_account |
| Payment_link Optional | Refer to Payment Link object section, nullable when payment_type is payment_link |
| Virtual_accounts array<virtual_account> Optional (Min 1) | Refer to Virtual Account object section, required and must not empty when payment_type is virtual_account |
| Amount Optional | Refer to Amount object section |
Response sample
{
"order_id": "7950c36a-d267-4f25-bb03-7a82b00z168t",
"invoice_number": "7128c81b-cde5-4c33-8777-4d1d0fcd6377",
"published_date": "2024-03-06 10:54:14 +0700",
"due_date": "2025-08-06 20:03:04 +0700",
"invoice_date": "2025-01-06 20:03:04 +0700",
"reference": "reference",
"customer_details": {
"id": "customer_id",
"name": "merchant A",
"email": "[email protected]",
"phone": "82313123123"
},
"item_details": [
{
"item_id": "SKU1111",
"description": "midtrans pillow",
"quantity": 1,
"price": 2000
}
],
"id": "65e7e8e657389830d04836fc",
"status": "pending",
"gross_amount": 13324,
"pdf_url": "https://assets.midtrans.com/invoices/pdf/5a76417e-be8e-437a-8e16-38c916aea614",
"payment_type": "payment_link",
"virtual_accounts": [],
"payment_link_url": "https://app.midtrans.com/payment-links/b1000b26-a311-42d4-9dc7-51a00ec8c681"
}
{
"error_messages": [
"item must not be empty",
"gross_amount must be more than 0"
]
}
--Occurred when creating an invoice using the same order id that was used previously.
{
"error_messages": [
"Duplicate order id"
]
}
{
"error_messages": [
"Internal server error"
]
}
| Field | Description |
|---|---|
| order_id String | Id for the order |
| id String | invoice id |
| invoice_number String | Number of the invoice |
| published_date String | Date of invoice is published/created in ISO 8601 format. Default time zone: GMT+7. |
| due_date String | Due date of transaction in ISO 8601 format. Default time zone: GMT+7. |
| invoice_date String | Date of Invoice and will be used in email and pdf created in ISO 8601 format. Default time zone: GMT+7. |
| customer_details Object | Refer to Customer Details object section. |
| item_details Array<item_detail> | Refer to Item Detail object section |
| payment_type String | Either payment_link or virtual_account |
| payment_link_url String | URL for payment link and only filled when payment_type is payment_link |
| virtual_accounts array <virtual_account> | Invoice virtual account and only filled when payment_type is virtual_account. Refer to Virtual Account object section. |
| pdf_url String | pdf_url of the invoice |
| gross_amount Integer | Total amount in invoice |
| status String | Status of the invoice, can be draft,pending, expired, overdue, paid, or voided |