> For the complete documentation index, see [llms.txt](https://qosic.gitbook.io/qospay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://qosic.gitbook.io/qospay/merchant-api/reporting/wallet-history.md).

# wallet history

```http
GET /api/v1/merchant/reports/wallet-history?page=0&size=20&walletId=301&direction=D&createdFrom=2026-08-01&createdTo=2026-08-10 HTTP/1.1
Host: api.example.com
Authorization: Bearer <access-token>
Accept: application/json
```

```bash
curl --get "https://api.example.com/api/v1/merchant/reports/wallet-history" \
  --header "Authorization: Bearer ${QOS_ACCESS_TOKEN}" \
  --header "Accept: application/json" \
  --data-urlencode "page=0" \
  --data-urlencode "size=20" \
  --data-urlencode "walletId=301" \
  --data-urlencode "direction=D" \
  --data-urlencode "createdFrom=2026-08-01" \
  --data-urlencode "createdTo=2026-08-10"
```

## Paramètres de requête

| Paramètre       | Obligatoire | Description                                                                                                                 |
| --------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| `page`          | Non         | Numéro de page indexé à partir de zéro ; valeur par défaut `0`.                                                             |
| `size`          | Non         | Taille de page comprise entre 1 et 100 ; valeur par défaut `20`.                                                            |
| `walletId`      | Non         | ID du wallet retourné par le rapport des wallets. Il doit appartenir au marchand authentifié et à son environnement actuel. |
| `transactionId` | Non         | ID interne de transaction retourné par le rapport des transactions.                                                         |
| `reference`     | Non         | Recherche partielle insensible à la casse sur la référence de l’historique du wallet.                                       |
| `direction`     | Non         | `C` pour crédit ou `D` pour débit.                                                                                          |
| `createdFrom`   | Non         | Date UTC de début inclusive, au format `yyyy-MM-dd`.                                                                        |
| `createdTo`     | Non         | Date UTC de fin inclusive, au format `yyyy-MM-dd`.                                                                          |

## Réponse réussie — HTTP 200

```json
{
  "data": {
    "items": [
      {
        "walletName": "Primary NGN Wallet",
        "reference": "9fdbf3f7-6f2b-4c7f-92cb-3d11b4a2cb01",
        "direction": "D",
        "amount": 5050.0,
        "currentBalance": 144950.0,
        "remarks": "FundTransfer|Invoice 1042 payout",
        "transactionId": 12045,
        "createdAt": "2026-08-10T14:20:31"
      }
    ],
    "pageNumber": 0,
    "pageSize": 20,
    "totalElements": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false
  },
  "message": "Wallet history retrieved successfully",
  "success": true,
  "responseCode": "00"
}
```

{% hint style="warning" %}
Si `walletId` n’appartient pas à l’environnement actuel du marchand, la réponse est HTTP `400` avec `Wallet not found`.
{% endhint %}

{% hint style="info" %}
Lorsque le marchand ne possède aucun wallet visible, l’endpoint renvoie HTTP `200` avec une page vide.
{% endhint %}