# Reporting et paiements (/fr/platform-api/reporting)
Ces endpoints donnent un accès programmatique aux données et paramètres également disponibles dans le tableau de bord de la Tapaya Platform. Vous pouvez les utiliser pour créer des tableaux de bord personnalisés, automatiser des processus ou récupérer des données de reporting, que vous intégriez l’Accept SDK ou que vous pilotiez directement l’application Tapaya Terminal. Leur authentification se fait de la même manière, avec votre Server Secret Token.
## Lister les commerçants [#list-merchants]
Listez les commerçants enregistrés dans cette organisation.
**Endpoint :** `GET /integrator/merchant`
cURL
```bash
curl -X 'GET' 'https://api.tapaya.com/integrator/merchant' \
-H 'Authorization: REPLACE_ME'
```
**Corps de la réponse :**
```json
[
{
"merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e",
"merchantToken": "unique_merchant_id_from_your_db",
"name": "Acme Corp",
"email": "admin@acme.com",
"businessType": 1,
"city": "Prague",
"country": 203,
"onboarded": true,
"isActive": true
}
]
```
Le champ `email` correspond à l’adresse e-mail d’administration / de contact actuellement enregistrée dans la fiche du commerçant. C’est la valeur que vous pouvez
utiliser pour rapprocher les fiches commerçants dans votre back-office sans avoir à récupérer chaque commerçant un par un.
## Récupérer l’historique des paiements [#retrieve-payment-history]
Obtenez la liste des 50 derniers paiements de l’ensemble des commerçants de votre organisation. C’est utile pour auditer les transactions ou créer une vue « Super Admin ».
Cet endpoint renvoie toujours les 50 derniers paiements de toute l’organisation ; il n’accepte pour l’instant aucun paramètre de requête pour
le commerçant, le statut, la plage de dates ou la pagination. Utilisez l’endpoint [Récupérer le détail d’un paiement](#retrieve-payment-details)
pour rechercher un paiement précis par son ID.
**Endpoint :** `GET /integrator/organization/payment`
cURL
```bash
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment' \
-H 'Authorization: REPLACE_ME'
```
**Corps de la réponse :**
```json
[
{
"paymentId": "018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f",
"paymentToken": "pay_abc123",
"paymentProcessorId": 1,
"paymentMethodId": 1,
"terminalId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a",
"locationId": "018f8f2a-6e4b-7f5d-ac4a-5b9d4eaf7a6b",
"requestedAmount": 1999,
"requestedCurrencyId": 1,
"settlementAmount": 1999,
"settlementCurrencyId": 1,
"statusId": 2,
"instrumentLabel": "VISA •••• 4242",
"instrumentIdentifier": "4242",
"createdAt": "2026-07-15T12:00:00Z",
"processedAt": "2026-07-15T12:00:03Z",
"merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e",
"merchantName": "Acme Corp"
}
]
```
## Statistiques agrégées [#aggregated-statistics]
Obtenez des statistiques de paiement agrégées sur l’ensemble des commerçants de votre organisation. Cet endpoint renvoie les volumes totaux par devise.
**Endpoint :** `GET /integrator/organization/payment/stats`
cURL
```bash
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/stats' \
-H 'Authorization: REPLACE_ME'
```
**Corps de la réponse :**
Un tableau contenant une entrée par devise dans laquelle votre organisation a traité des paiements.
```json
[
{
"currencyId": 1,
"amount": 4582317
}
]
```
## Récupérer le détail d’un paiement [#retrieve-payment-details]
Obtenez le détail complet d’un paiement, y compris ses transactions sous-jacentes, ses débits et ses éventuels remboursements. La portée est limitée à votre organisation ; les paiements appartenant à une autre organisation renvoient `404`.
Un **paiement** (payment) est la demande d’achat dans son ensemble : un montant fixe pour un moyen de paiement. Il contient une ou
plusieurs **transactions**, chacune représentant une tentative de faire circuler l’argent via un processeur. Une transaction contient
un ou plusieurs **débits** (charges), chacun étant un événement de règlement concret sur un instrument précis (carte, portefeuille, compte
bancaire).
La plupart des paiements comportent exactement une transaction avec un débit. Un paiement peut comporter plusieurs transactions lorsqu’une
présentation sans contact sur le terminal de paiement est retentée (chaque tentative est rattachée comme une transaction distincte). Une transaction peut comporter
plusieurs débits pour les moyens de paiement asynchrones comme la crypto ou le virement bancaire, pour lesquels le processeur signale
au fil du temps des événements de règlement partiels ou répétés (par exemple une facture crypto sous-payée complétée par un second
paiement on-chain). Les remboursements font directement référence au paiement et au débit ; ils ne sont pas imbriqués sous les transactions.
`statusId` (`StatusEnum`) reflète l’état actuel du paiement :
| Valeur | Nom | Description |
| ------ | -------------- | -------------------------------------------------------------------------- |
| `1` | `Pending` | La transaction a été créée mais n’est pas encore finalisée. |
| `2` | `Success` | La transaction s’est terminée avec succès. |
| `3` | `Cancelled` | La transaction a été annulée avant d’être terminée. |
| `4` | `Refunded` | La transaction a été remboursée après avoir été terminée. |
| `5` | `Failed` | La transaction n’a pas pu aboutir. |
| `6` | `ActionNeeded` | La transaction nécessite une action supplémentaire du client pour aboutir. |
**Endpoint :** `GET /integrator/organization/payment/{paymentId}`
cURL
```bash
curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f' \
-H 'Authorization: REPLACE_ME'
```
**Réponses :**
| Code | Description |
| ----- | -------------------------------------------------------------- |
| `200` | Paiement trouvé |
| `404` | Paiement introuvable ou n’appartenant pas à votre organisation |
**Corps de la réponse :**
```json
{
"paymentId": "018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f",
"paymentToken": "pay_abc123",
"paymentProcessorId": 1,
"paymentMethodId": 1,
"terminalId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a",
"locationId": "018f8f2a-6e4b-7f5d-ac4a-5b9d4eaf7a6b",
"requestedAmount": 1999,
"requestedCurrencyId": 1,
"settlementAmount": 1999,
"settlementCurrencyId": 1,
"referralFee": 30,
"statusId": 2,
"terminalName": "Front Counter",
"locationName": "Acme Corp, Prague",
"merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e",
"merchantName": "Acme Corp",
"createdAt": "2026-07-15T12:00:00Z",
"processedAt": "2026-07-15T12:00:03Z",
"transactions": [
{
"transactionId": "018f8f2a-7f5c-7a6e-bd5b-6cae5fb0879c",
"statusId": 2,
"referenceInfo": null,
"fxRate": 1.0,
"createdAt": "2026-07-15T12:00:00Z",
"processedAt": "2026-07-15T12:00:03Z",
"cancelledAt": null,
"charges": [
{
"chargeId": "018f8f2a-8a6d-7b7f-ce6c-7dbf6ac1980d",
"chargeToken": "charge_abc123",
"statusId": 2,
"instrumentLabel": "VISA •••• 4242",
"instrumentIdentifier": "4242",
"authorizationReference": "123456",
"requestedAmount": 1999,
"requestedCurrencyId": 1,
"settlementAmount": 1999,
"settlementCurrencyId": 1,
"fxRate": 1.0,
"createdAt": "2026-07-15T12:00:03Z"
}
]
}
],
"refunds": []
}
```
## Rembourser un paiement [#refund-a-payment]
Remboursez un paiement, en totalité ou en partie. Omettez `amount` pour rembourser l’intégralité du montant réglé restant.
**Endpoint :** `POST /integrator/organization/payment/{paymentId}/refund`
cURL
```bash
curl -X 'POST' 'https://api.tapaya.com/integrator/organization/payment/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/refund' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
"amount": 1999,
"refundReasonId": 1
}'
```
**Paramètres :**
| Champ | Type | Obligatoire | Description |
| ---------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `amount` | `long` | | Montant à rembourser, dans la plus petite unité de la devise. Omettez-le pour un remboursement total du montant réglé restant. |
| `refundReasonId` | `int` | ✓ | Motif du remboursement (`RefundReasonEnum`). |
**Réponses :**
| Code | Description |
| ----- | ------------------------------------------------------------------------------------------------------------------------- |
| `200` | Remboursement initié |
| `400` | Erreur de validation de la requête |
| `404` | Paiement introuvable ou n’appartenant pas à votre organisation |
| `409` | Le paiement ne peut pas être remboursé dans son état actuel, ou le montant demandé dépasse le montant encore remboursable |
**Corps de la réponse :**
```json
{
"refundId": "018f8f2a-9b7e-7c8a-df7d-8ecf7bd2a91e",
"refundToken": "refund_abc123",
"statusId": 1,
"refundReasonId": 1,
"requestedAmount": 1999,
"requestedCurrencyId": 1,
"settlementAmount": 1999,
"settlementCurrencyId": 1,
"fxRate": 1.0,
"authorizationReference": null,
"referralFeeRefund": null,
"createdAt": "2026-07-15T12:05:00Z",
"processedAt": null
}
```
`referralFeeRefund` et `processedAt` sont renseignés de manière asynchrone
une fois que le processeur a confirmé le remboursement. Ils valent toujours `null` dans la réponse immédiate ; interrogez régulièrement
[Récupérer le détail d’un paiement](#retrieve-payment-details) pour connaître l’état final. L’historique des paiements ne renvoie que
les paiements les plus récents, un paiement remboursé plus ancien peut donc ne plus y figurer.