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",
"invoice_title": "INVOICE",
"invoice_paid_title": "INVOICE",
"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",
"invoice_title": "INVOICE",
"invoice_paid_title": "INVOICE",
"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 |
invoice_number | Number of the invoice |
due_date | Due date of transaction in ISO 8601 format. Default time zone: GMT+7 and has to be after invoice_date. For example: |
invoice_date | Date of Invoice and will be used in email and PDF created in ISO 8601 format. Default time zone: GMT+7. For example: |
invoice_title | Title of the Invoice on creation. This will be used on Invoice PDF when the Invoice is not paid yet. |
invoice_paid_title | Title of the Invoice when status is Paid. This will be used on Invoice PDF when the Invoice is paid. |
Customer_details | Refer to Customer Details object section. |
Reference | Reference of the invoice |
Item_details | Refer to Item Detail object section |
Notes | Notes of the invoice |
Payment_type | Either payment_link or virtual_account |
Payment_link | Refer to Payment Link object section, nullable when payment_type is payment_link |
Virtual_accounts | Refer to Virtual Account object section, required and must not empty when payment_type is virtual_account |
Amount | Refer to Amount object section |
Response sample
{
"order_id": "7950c36a-d267-4f25-bb03-7a82b00z168t",
"invoice_number": "7128c81b-cde5-4c33-8777-4d1d0fcd6377",
"invoice_title": "INVOICE",
"invoice_paid_title": "INVOICE",
"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 | invoice id |
invoice_number | Number of the invoice |
invoice_title | Title of the Invoice on creation. This will be used on Invoice PDF when the Invoice is not paid yet. |
invoice_paid_title | Title of the Invoice when status is Paid. This will be used on Invoice PDF when the Invoice is paid. |
due_date | Due date of transaction in ISO 8601 format. Default time zone: GMT+7. |
invoice_date | Date of Invoice and will be used in email and pdf created in ISO 8601 format. Default time zone: GMT+7. |
customer_details | Refer to Customer Details object section. |
item_details | Refer to Item Detail object section |
payment_type | Either payment_link or virtual_account |
payment_link_url | URL for payment link and only filled when payment_type is payment_link |
virtual_accounts | Invoice virtual account and only filled when payment_type is virtual_account. Refer to Virtual Account object section. |
pdf_url | pdf_url of the invoice |
gross_amount | Total amount in invoice |
status | Status of the invoice, can be |