# Invoice management APIs

{% hint style="info" %}
To accept a payment using IremboPay API, the first step is to create an invoice. An invoice can have an expiration date which defines until when it can be paid.
{% endhint %}

## API Authentication

\
The IremboPay API uses a secret key to authenticate requests. Merchants can view and manage their API secret key in the IremboPay merchant portal. All requests shall be authenticated by providing:

{% tabs %}
{% tab title="Merchant API Secret Key" %}
**Header Key:** `irembopay-secretkey`
{% endtab %}

{% tab title="API Version" %}

* **Header Key:** `X-API-Version`
* **Value:** `1`
  {% endtab %}
  {% endtabs %}

***

## API Response

{% hint style="info" %}
IrenboPay API calls return HTTP status codes and JSON response bodies.
{% endhint %}

### HTTP Status codes

<table><thead><tr><th width="253">Status code</th><th>Description</th></tr></thead><tbody><tr><td>200, 201</td><td> The request was successfully executed.</td></tr><tr><td>400</td><td>Missing required parameters, or parameters not correctly formatted.</td></tr><tr><td>401</td><td>Authentication has failed.</td></tr><tr><td>404</td><td>A specified resource in the request does not exist.</td></tr><tr><td>429</td><td>Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.</td></tr><tr><td>500, 502, 503, 504</td><td>An internal server error has occurred.</td></tr></tbody></table>

### Response body

*The response body is a JSON object structured as follows:*

```json
    {
       "success" : <true or false>,
       "message" : “string”,
       "data" : {},
       "errors" : []
    }
```

**Fields Description:**

1. **`success`**
   * **Type:** Boolean (`true` or `false`)
   * **Description:** Indicates whether the request was successful and a payload has been returned. If `false`, the `errors` field will contain details.
2. **`message`**
   * **Type:** String
   * **Description:** A human-readable message providing additional context about the request's result (success or failure).
3. **`data`**
   * **Type:** Object
   * **Description:** The actual response payload. Its structure is specific to each endpoint and is returned when the HTTP status code is **200** or **201**.
4. **`errors`**

   * **Type:** Array of Error Objects
   * **Description:** Contains an array of error objects, returned when the HTTP status code is not **200** or **201**. Each error object includes the following fields:
   * **`code`**: A string representing the error code.
   * **`detail`**: A human-readable description of the error.

   **Error code for authentication error**

   <table><thead><tr><th width="181">Status code</th><th width="259">Description</th><th>Error message</th></tr></thead><tbody><tr><td>401</td><td>AUTHENTICATION_FAILED</td><td>Invalid IremboPay secret key</td></tr></tbody></table>