> ## Documentation Index
> Fetch the complete documentation index at: https://beta-developers.mizaniyapay.dz/llms.txt
> Use this file to discover all available pages before exploring further.

# Static QR Code API: Amount Configuration

> Attach and clear DZD payment amounts on static QR codes for the Mizaniya Pay platform using two REST endpoints.

The Static QR Code Amount Configuration API lets integration partners control which payment amounts a customer sees after scanning a static QR code on the Mizaniya Pay platform. All amounts are in Algerian Dinars (DZD). You can attach a list of preset amounts to a QR code, make it expire at a specific time, and optionally clear the configuration after the first successful payment. Two simple POST endpoints manage the lifecycle of these configurations.

<CardGroup cols={2}>
  <Card title="Attach configuration" icon="plus" href="/api-reference/qr-codes/set-qr-config">
    Set amounts, expiration, and single-use behavior on a QR code.
  </Card>

  <Card title="Remove configuration" icon="trash" href="/api-reference/qr-codes/un-set-qr-config">
    Clear the entire configuration from a QR code.
  </Card>
</CardGroup>

## How it works

When a customer scans a QR code you configured, they are taken to the Mizaniya Pay payment platform. What they see next depends on how many amounts you attached.

* **Multiple amounts**: the customer is presented with a list of preset DZD amounts and must choose one.
* **Single amount**: no selection step appears. The platform shows the single preset amount directly.

## Configuration modes

You can tailor each QR code to your business flow using three configuration modes.

| Mode             | Description                                                                                    | Best for                                 |
| ---------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------- |
| **Permanent**    | Omit `expiresAt` or pass `null`. The config stays active indefinitely.                         | Recurring payment points, donation boxes |
| **Time-limited** | Set `expiresAt` to an ISO 8601 timestamp. Config is active until that moment, then ignored.    | Seasonal campaigns, event tickets        |
| **Single-use**   | Set `singleUse: true`. The platform auto-clears the config after the first successful payment. | One-off invoices, per-customer fees      |

Calling `/set-qr-config` again for the same QR code token **replaces** the previous configuration entirely.

## Endpoints

| Method | Endpoint                          | Purpose                                          |
| ------ | --------------------------------- | ------------------------------------------------ |
| `POST` | `{api_base_url}/set-qr-config`    | Attach or replace a QR code amount configuration |
| `POST` | `{api_base_url}/un-set-qr-config` | Remove the configuration from a QR code          |

Both endpoints expect JSON request bodies and require the same authentication header.

## Prerequisites

Before making API calls, retrieve the following values from the Mizaniya Partner Platform.

* `api_base_url`: the root URL for all API requests in your environment
* `api_key`: used in the `x-api-key` request header
* `token`: the unique identifier of the static QR code you want to configure

<Note>
  Store your API key securely. Do not commit it to source control or expose it in client-side code.
</Note>

## Authentication

Every request must include the `x-api-key` header. A missing or invalid key returns `401 Unauthorized` with a structured error body.

```text theme={null}
x-api-key: <your_api_key>
```

<Warning>
  If you receive a `401` response, verify that the header name is exactly `x-api-key` and the value matches the key shown in the Partner Platform.
</Warning>

## Response model overview

Responses follow one of several consistent envelope shapes. When handling errors, branch on the `errorCode` field instead of parsing message text.

| Status | Shape                                                                  | When it occurs                                   |
| ------ | ---------------------------------------------------------------------- | ------------------------------------------------ |
| `200`  | `{ statusCode, message }`                                              | Successful `/set-qr-config` call                 |
| `204`  | Empty body                                                             | Successful `/un-set-qr-config` call              |
| `400`  | `{ statusCode, message, error }` or `{ statusCode, message[], error }` | Validation failure or malformed request          |
| `401`  | `{ statusCode, message, errorCode, timestamp }`                        | Missing or invalid `x-api-key`                   |
| `4xx`  | `{ statusCode, message, errorCode, timestamp, details }`               | Business rule violation (e.g. QR code not found) |

## Error code reference

| errorCode                       | HTTP  | Meaning                                                                             |
| ------------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `AUTH401_UNAUTHORIZED_ACCESS`   | `401` | The `x-api-key` header is missing or invalid                                        |
| `QR_CODE404_NOT_FOUND`          | `404` | No QR code exists for the supplied token                                            |
| `QR_CODE400_CANNOT_BE_MODIFIED` | `400` | The QR code state does not allow configuration changes                              |
| `QR_CODE400_INVALID_STATUS`     | `400` | The QR code status is invalid for this operation (for example, disabled or revoked) |
| `VALIDATION400`                 | `400` | Generic validation failure for a malformed request body                             |