Create Batch Invoice

This API allows merchants to create a batch payment request. This scenario is useful when a set of invoices will be paid in a batch using a single invoice number.

Key business rules

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

Method: POST /payments/invoices/batch

Headers

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

Request body

Data representation: JSON.

Name	Type	Description
transactionId	String	Yes	A unique transaction identifier generated by the merchant.
invoiceNumbers	Array	Yes	Array of invoice numbers which shall be linked to the batch invoice.
description	String	No	Identifier of the Payment Account where the money will be deposited. It also determines the currency of the invoice.

---

Response body payload

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

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

---

Error codes

HTTP code	Error code	Description
400	INVOICES_MISSING	No invoice provided.
400	BAD_INVOICES_CURRENCY	All invoices do not have the same currency.
400	BAD_INVOICES_PAYMENT_ACCOUNT	All invoices do not have the same payment account.
400	BAD_INVOICES_PAYMENT_EXPIRED	An invoice is expired
400	BAD_INVOICES_IN_BATCH	An invoice is already in a batch invoice
400	BAD_INVOICES_PAID	An invoice is paid
400	TRANSACTION_ID_MISSING	No transaction id provided
400	DUPLICATE_TRANSACTION_ID	The provided transaction Id already exists.
404	INVOICE_NOT_FOUND	An invoice provided does not exist under the merchant.

---

Create a batch of invoices

post

Body

application/json

invoiceNumbersstring[]Required

List of invoice numbers to be processed in the batch

transactionIdstringRequired

The transaction ID associated with the batch

descriptionstringRequired

Description for the batch of invoices

Responses

201

Batch Invoice created successfully

application/json

400

Invalid request

application/json

401

Unauthorized

application/json

404

Not Found

application/json

post

/payments/invoices/batch

PayloadJavaScriptJavaPython

{
  "invoiceNumbers": [
    "880523335346",
    "880522008336"
  ],
  "transactionId": "TST-10010",
  "description": "Batch description"
}

{
  "message": "Batch Invoice created successfully",
  "success": true,
  "data": {
    "amount": 100,
    "invoiceNumber": "870928493217",
    "transactionId": "TST-1005",
    "createdAt": "2023-04-19T11:58:02.895+02",
    "updatedAt": "2023-04-19T11:58:02.895+02",
    "expiryAt": "2024-09-30T01:00:00.000+02",
    "paymentAccountIdentifier": "RCA-RWF",
    "paymentItems": [
      {
        "unitAmount": 2000,
        "quantity": 1,
        "code": "PI-3e5fe23f2d"
      }
    ],
    "description": "Invoice description",
    "language": "EN",
    "type": "BATCH",
    "paymentStatus": "NEW",
    "currency": "RWF",
    "customer": {
      "email": "[e-mail]",
      "phoneNumber": "0780000001",
      "name": "Jixle Manzi"
    },
    "batchNumber": "870928493217",
    "childInvoices": [
      "880419591102"
    ],
    "paymentLinkUrl": "<checkoutUrl>/880419591102"
  }
}