Create Invoice

Key details of the API

1. Resource URL

Test

https://api.sandbox.irembopay.com/payments/invoices

Production

1. Method: POST

2. Headers

irembopay-secretKey: secreKey
X-API-Version: 3

Create a invoice api reference

POST /payments/invoices

Headers

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

Body

Data representation: JSON

Name	Type	Mandatory	Comment
transactionId	string	Yes	A unique transaction identifier generated by the merchant.
paymentItems	Array	Yes	List of products to include in the invoice. Each product has a unit amount. Find more details on the structure of this array after this table.
paymentAccountIdentifier	String	Yes	Identifier of the Payment Account where the money will be deposited. It also determines the currency of the invoice.
expiryAt	String	No	Time at which the payment request will expire, in Internet date and time format. eg.2022-11-27T16:24:51.000+02:00
description	String	No	An optional description of the invoice.
customer	Object	No	An optional customer object who will be notified about this invoice.
language	String	No	Language provided during the creation of the invoice. Possible values: FR, EN, RW.
partialPaymentEnabled	Boolean	No	An indicator to show if partial payment is supported on the API
installmentPlan	Enum	Yes (if partialPaymentEnabled)	Type of installment plan: FLAT or PERCENTAGE
installments	Array	Yes (if partialPaymentEnabled)	List of installment definitions (cannot be empty)

The paymentItems array is composed of objects with fields below:

Name	Type	Mandatory?	Comments
code	String	Yes	Identifier of the product
quantity	Integer	Yes	Must be > 0
unitAmount	Double	Yes

The customer object, when provided, is composed of fields below:

Name	Type	Mandatory?	Comments
email	String	No
phoneNumber	Integer	No
name	String	No

---

---

Installments

The installments array, when provided, is composed of fields below:

Field	Type	Required	Description
order	integer	Yes	Order number of the installment (1, 2, 3, etc.). Determines payment sequence
amount	decimal	Yes (for FLAT plan)	Fixed amount for this installment (for FLAT plan)
value	decimal	Yes (for PERCENTAGE plan)	Percentage value for this installment (for PERCENTAGE plan, minimum: 1)

Installment Plan Types

FLAT Plan

In a FLAT plan, each installment has a fixed amount. The sum of all installment amounts must equal the total invoice amount.

Example:

• Invoice Amount: 30,000 RWF

• Installment 1: 10,000 RWF

• Installment 2: 10,000 RWF

• Installment 3: 10,000 RWF

• Total: 30,000 RWF ✓

Request Structure:

{
  "partialPaymentEnabled": true,
  "installmentPlan": "FLAT",
  "installments": [
    {
      "order": 1,
      "amount": 10000.00
    },
    {
      "order": 2,
      "amount": 10000.00
    },
    {
      "order": 3,
      "amount": 10000.00
    }
  ]
}

---

PERCENTAGE Plan

In a PERCENTAGE plan, each installment is defined as a percentage of the total invoice amount. The percentages must sum to exactly 100%, and the calculated amounts must equal the total invoice amount.

Example:

• Invoice Amount: 30,000 RWF

• Installment 1: 50% = 15,000 RWF

• Installment 2: 30% = 9,000 RWF

• Installment 3: 20% = 6,000 RWF

• Total: 100% = 30,000 RWF ✓

Request Structure:

{
  "partialPaymentEnabled": true,
  "installmentPlan": "PERCENTAGE",
  "installments": [
    {
      "order": 1,
      "value": 50.00
    },
    {
      "order": 2,
      "value": 30.00
    },
    {
      "order": 3,
      "value": 20.00
    }
  ]
}

Important:

• Percentage values must be ≥ 1

• Total of all percentages must equal exactly 100%

• Amounts are calculated automatically from percentages

---

Important Notes

• API Version: Partial payments are only available in API V3. Using V1 or V2 will result in an error if partial payments are enabled.

• Installment Plan Required: When partialPaymentEnabled is true, installmentPlan and installments are required.

• Total Validation: The sum of all installment amounts must equal the total invoice amount (after discounts).

• Order Sequence: Installments must be ordered sequentially (1, 2, 3, etc.) and will be paid in that order.

---

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.
paymentLinkUrl	String	Yes	A URL that directs the merchants' end-user to a checkout page where they can make a payment.

---

Error codes

HTTP code	Error code	Description
400	TRANSACTION_ID_MISSING	No transaction id provided
400	DUPLICATE_TRANSACTION_ID	The provided transaction Id already exists
400	PRODUCT_MISSING	No product provided.
400	BAD_PRODUCT	An item of the products array is incorrectly formatted or has missing parameters.
400	PAYMENT_ACCOUNT_MISSING	paymentAccountIdentifier parameter is missing.
400	BAD_EXPIRATION_DATE	The expiration date is incorrectly formatted or is in the past
400	BAD_LANGUAGE	The language is incorrectly formatted.
400	BAD_CUSTOMER_CONTACT	A CustomerContact is incorrectly formatted.
400	PAYMENT_ACCOUNT_NOT_FOUND	The payment account identifier provided does not exist under the merchant.
400	PRODUCT_NOT_FOUND	A product provided does not exist under the merchant.

---

Open API Sample

Create a new invoice

post

Authorizations

apiKeyAuth

irembopay-secretKeystringRequired

Body

application/json

transactionIdstringRequired

paymentAccountIdentifierstringRequired

descriptionstringRequired

expiryAtstring · date-timeRequired

languagestringRequired

Responses

200

Invoice created successfully

application/json

400

Invalid request

application/json

401

Unauthorized request

application/json

post

/payments/invoices

PayloadJavaScriptJavaPython

{
  "transactionId": "TST-10020",
  "paymentAccountIdentifier": "TST-RWF",
  "customer": {
    "email": "[e-mail]",
    "phoneNumber": "0780000001",
    "name": "Jixle Manzi"
  },
  "paymentItems": [
    {
      "unitAmount": 2000,
      "quantity": 1,
      "code": "PI-3e5fe23f2d"
    }
  ],
  "description": "Invoice description",
  "expiryAt": "2024-09-30T01:00:00+02:00",
  "language": "EN"
}

{
  "message": "Invoice created successfully",
  "success": true,
  "data": {
    "amount": 100,
    "invoiceNumber": "880419623157",
    "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",
    "type": "SINGLE",
    "paymentStatus": "NEW",
    "currency": "RWF",
    "customer": {
      "email": "[e-mail]",
      "phoneNumber": "0780000001",
      "name": "Jixle Manzi"
    },
    "language": "EN",
    "paymentLinkUrl": "<checkoutUrl>/880419623157"
  }
}