# Create Invoice

## Key details of the API

1. **Resource URL**

{% tabs %}
{% tab title="Test" %}

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

{% endtab %}

{% tab title="Production" %}

```javascript
https://api.irembopay.com/payments/invoices
```

{% endtab %}
{% endtabs %}

2. **Method: `POST`**
3. **Headers**

```javascript
irembopay-secretKey: secreKey
X-API-Version: 2
```

## Create a invoice api reference

<mark style="color:green;">`POST`</mark> `/payments/invoices`

**Headers**

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

**Body**

**Data representation**: JSON

<table><thead><tr><th width="155">Name</th><th width="103">Type</th><th width="110">Mandatory</th><th width="384">Comment</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>paymentItems</td><td>Array</td><td>Yes</td><td>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.</td></tr><tr><td>paymentAccountIdentifier</td><td>String</td><td>Yes</td><td>Identifier of the Payment Account where the money will be deposited. It also determines the currency of the invoice.</td></tr><tr><td>expiryAt</td><td>String</td><td>No</td><td>Time at which the payment request will expire, in Internet date and time format. eg.<code>2022-11-27T16:24:51.000+02:00</code></td></tr><tr><td>description</td><td>String</td><td>No</td><td>An optional description of the invoice.</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>language</td><td>String</td><td>No</td><td>Language provided during the creation of the invoice. Possible values: <code>FR</code>, <code>EN</code>, <code>RW</code>.</td></tr></tbody></table>

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 <a href="#response-body-payload" id="response-body-payload"></a>

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

<table><thead><tr><th width="247">Name</th><th width="92">Type</th><th width="112">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>paymentLinkUrl</td><td>String</td><td>Yes</td><td>A URL that directs the merchants' end-user to a checkout page where they can make a payment.</td></tr></tbody></table>

***

### Error codes <a href="#error-codes" id="error-codes"></a>

<table><thead><tr><th width="125">HTTP code</th><th width="311">Error code	</th><th>Description</th></tr></thead><tbody><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>400</td><td>PRODUCT_MISSING</td><td>No product provided.</td></tr><tr><td>400</td><td>BAD_PRODUCT</td><td>An item of the products array is incorrectly formatted or has missing parameters.</td></tr><tr><td>400</td><td>PAYMENT_ACCOUNT_MISSING</td><td>paymentAccountIdentifier parameter is missing.</td></tr><tr><td>400</td><td>BAD_EXPIRATION_DATE</td><td>The expiration date is incorrectly formatted or is in the past</td></tr><tr><td>400</td><td>BAD_LANGUAGE</td><td>The language is incorrectly formatted.</td></tr><tr><td>400</td><td>BAD_CUSTOMER_CONTACT</td><td>A CustomerContact is incorrectly formatted.</td></tr><tr><td>400</td><td>PAYMENT_ACCOUNT_NOT_FOUND</td><td>The payment account identifier provided does not exist under the merchant.</td></tr><tr><td>400</td><td>PRODUCT_NOT_FOUND</td><td>A product provided does not exist under the merchant.</td></tr></tbody></table>

***

## Open API Sample

{% openapi src="<https://300693647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPMrOhz6Tb846tjeUnjlw%2Fuploads%2Fu3JES8raxSE8pvNjbGqp%2Fcreate_invoice.json?alt=media&token=c3aaca42-4bf8-413c-a349-2967585a1d13>" path="/payments/invoices" method="post" %}
[create\_invoice.json](https://300693647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPMrOhz6Tb846tjeUnjlw%2Fuploads%2Fu3JES8raxSE8pvNjbGqp%2Fcreate_invoice.json?alt=media\&token=c3aaca42-4bf8-413c-a349-2967585a1d13)
{% endopenapi %}