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: 2

Create a invoice api reference

POST /payments/invoices

Headers

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

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.

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

---

---

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"
  }
}