Reporting et paiements

Listez les commerçants, récupérez l’historique et le détail des paiements, consultez les statistiques et remboursez des paiements.

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

Listez les commerçants enregistrés dans cette organisation.

Endpoint : GET /integrator/merchant

curl -X 'GET' 'https://api.tapaya.com/integrator/merchant' \
-H 'Authorization: REPLACE_ME'

Corps de la réponse :

[
    {
        "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

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 ».

Ni filtrage ni pagination

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 pour rechercher un paiement précis par son ID.

Endpoint : GET /integrator/organization/payment

curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment' \
-H 'Authorization: REPLACE_ME'

Corps de la réponse :

[
    {
        "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

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 -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.

[
    {
        "currencyId": 1,
        "amount": 4582317
    }
]

Récupérer le détail d’un paiement

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.

Paiement, transaction et débit

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 -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 :

{
    "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

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 -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 :

{
    "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
}

Règlement asynchrone

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 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.

Il manque quelque chose sur cette page ?Demandez une fonctionnalité. Nous joignons cette page pour que l’équipe ait le contexte.

Reporting et paiements

Lister les commerçants

Récupérer l’historique des paiements

Statistiques agrégées

Récupérer le détail d’un paiement

Rembourser un paiement

Sur cette page