# Create Batch Invoice

## Key business rules <a href="#key-business-rules" id="key-business-rules"></a>

1. All invoices of a batch shall have the same currency.
2. All invoices of a batch shall have the same payment account identifier.
3. An expired invoice cannot be included in a batch.
4. An invoice can only be included in one and only one batch.
5. A paid invoice cannot be included in a batch.
6. The expiration time of a batch invoice is the earliest expiration time of all the linked invoices.
7. Once an invoice is in a batch, it cannot be paid individually anymore.
8. A batch invoice cannot be paid partially.
9. Once a batch invoice is paid, all the linked invoices will be marked as paid in IremboPay, but IremboPay will notify the merchant endpoint only for the batch payment (linked invoices will not be included in the payment notifications).

***

## Create a batch invoice API reference

&#x20;**Method**: <mark style="color:green;">`POST`</mark>` ``/payments/invoices/batch`

### **Headers**

| Name                | Value              |
| ------------------- | ------------------ |
| Content-Type        | `application/json` |
| irembopay-secretKey | secreKey           |
| X-API-Version       | 2                  |

### Request body <a href="#request-body" id="request-body"></a>

**Data representation**: JSON.

<table><thead><tr><th>Name</th><th width="106">Type</th><th width="87">Description</th><th></th></tr></thead><tbody><tr><td>transactionId</td><td>String</td><td>Yes</td><td>A unique transaction identifier generated by the merchant.</td></tr><tr><td>invoiceNumbers</td><td>Array</td><td>Yes</td><td>Array of invoice numbers which shall be linked to the batch invoice.</td></tr><tr><td>description</td><td>String</td><td>No</td><td>Identifier of the Payment Account where the money will be deposited. It also determines the currency of the invoice.</td></tr></tbody></table>

***

### Response body payload <a href="#response-body-payload" id="response-body-payload"></a>

For this endpoint, the "data" payload in the response will have the fields below:<br>

<table><thead><tr><th width="179">Name</th><th width="117">Type</th><th width="155">Mandatory?</th><th>Comments</th></tr></thead><tbody><tr><td>invoiceNumber</td><td>String</td><td>Yes</td><td>Identifier of the invoice that the end-user will use to do the payment.</td></tr><tr><td>transactionId</td><td>String</td><td>Yes</td><td>Transaction Identifier provided during the creation of the invoice.</td></tr><tr><td>paymentAccountIdentifier</td><td>String</td><td>Yes</td><td>Identifier of the Payment Account where the money will be deposited.</td></tr><tr><td>paymentItems</td><td>Array</td><td>Yes</td><td>Products for which this invoice has been created.</td></tr><tr><td>paymentStatus</td><td>String</td><td>Yes</td><td>Payment status of the invoice:<br><code>NEW</code>: invoice created and not paid yet. <code>PAID</code>: paid invoice.</td></tr><tr><td>amount</td><td>double</td><td>Yes</td><td>Amount of the invoice. Calculation method : Sum of (Product unit amount x quantity)</td></tr><tr><td>currency</td><td>String</td><td>Yes</td><td>Currency of the invoice which is the same as the currency of the payment account identifier. Possible values: "RWF", "EUR", "GBP", "USD".</td></tr><tr><td>type</td><td>String</td><td>Yes</td><td><code>SINGLE</code> or <code>BATCH</code></td></tr><tr><td>createdAt</td><td>String</td><td>Yes</td><td>In <a href="https://datatracker.ietf.org/doc/html/rfc3339#section-5.6">Internet date and time format</a>.<br>eg.<code>2022-11-27T16:24:51.000+02:00</code></td></tr><tr><td>updatedAt</td><td>String</td><td>No</td><td>In <a href="https://datatracker.ietf.org/doc/html/rfc3339#section-5.6">Internet date and time format</a>.<br>eg.<code>2022-11-27T16:24:51.000+02:00</code></td></tr><tr><td>expiryAt</td><td>String</td><td>No</td><td>In <a href="https://datatracker.ietf.org/doc/html/rfc3339#section-5.6">Internet date and time format</a>.<br>eg.<code>2022-11-27T16:24:51.000+02:00</code></td></tr><tr><td>customer</td><td>Object</td><td>No</td><td>An optional customer object who will be notified about this invoice.</td></tr><tr><td>description</td><td>String</td><td>No</td><td>Optional description provided at invoice creation.</td></tr><tr><td>childInvoices</td><td>Array</td><td>No</td><td>If this invoice is a batch invoice, this is an array of invoice numbers which are included in the batch.</td></tr><tr><td>language</td><td>String</td><td>No</td><td>Language provided during the creation of the invoice.<br>Possible values: <code>FR</code>, <code>EN</code>, <code>RW</code></td></tr><tr><td>batchNumber</td><td>String</td><td>No</td><td>Batch invoice number (only for invoice with type: <code>BATCH</code>)</td></tr><tr><td>paymentLinkUrl</td><td>String</td><td>Yes</td><td>Batch invoice number (only for invoice with type: <code>BATCH</code>)</td></tr></tbody></table>

***

## Error codes

<table><thead><tr><th width="126">HTTP code</th><th>Error code</th><th width="322">Description</th></tr></thead><tbody><tr><td>400</td><td>INVOICES_MISSING</td><td>No invoice provided.</td></tr><tr><td>400</td><td>BAD_INVOICES_CURRENCY</td><td>All invoices do not have the same currency.</td></tr><tr><td>400</td><td>BAD_INVOICES_PAYMENT_ACCOUNT</td><td>All invoices do not have the same payment account.</td></tr><tr><td>400</td><td>BAD_INVOICES_PAYMENT_EXPIRED</td><td>An invoice is expired</td></tr><tr><td>400</td><td>BAD_INVOICES_IN_BATCH</td><td>An invoice is already in a batch invoice</td></tr><tr><td>400</td><td>BAD_INVOICES_PAID</td><td>An invoice is paid</td></tr><tr><td>400</td><td>TRANSACTION_ID_MISSING</td><td>No transaction id provided</td></tr><tr><td>400</td><td>DUPLICATE_TRANSACTION_ID</td><td>The provided transaction Id already exists.</td></tr><tr><td>404</td><td>INVOICE_NOT_FOUND</td><td>An invoice provided does not exist under the merchant.</td></tr></tbody></table>

***

{% openapi src="<https://300693647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPMrOhz6Tb846tjeUnjlw%2Fuploads%2Fop8cnC5JZDRDPzPy6iV1%2Fcreate_batch_invoice.json?alt=media&token=c36d4e2b-da11-493c-8159-64942120e28f>" path="/payments/invoices/batch" method="post" %}
[create\_batch\_invoice.json](https://300693647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPMrOhz6Tb846tjeUnjlw%2Fuploads%2Fop8cnC5JZDRDPzPy6iV1%2Fcreate_batch_invoice.json?alt=media\&token=c36d4e2b-da11-493c-8159-64942120e28f)
{% endopenapi %}