BCard - Documentation technique

PaymentApiController extends AbstractController
in package

Contrôleur d'API de consultation des paiements.

Il expose en lecture seule l'historique des paiements rattachés à l'utilisateur authentifié : liste paginée et filtrable par statut, détail d'un paiement (avec la commande associée et la référence Stripe payment_intent) et statistiques agrégées sur une période glissante. Aucune écriture n'est réalisée : la création des paiements relève du tunnel de commande et des webhooks Stripe.

Préfixe de route : /api/payments. Toutes les actions exigent IS_AUTHENTICATED_FULLY (jeton JWT bearerAuth).

Attributes
#[Route]
'/api/payments'
$name: 'api_payments_'
#[Tag]
$name: 'Payments'
$description: 'Gestion des paiements'

Table of Contents

Properties

$entityManager  : EntityManagerInterface
$serializer  : SerializerInterface

Methods

__construct()  : mixed
list()  : JsonResponse
Retourne la liste paginée des paiements de l'utilisateur authentifié.
show()  : JsonResponse
Retourne le détail d'un paiement.
stats()  : JsonResponse
Retourne des statistiques agrégées sur les paiements de l'utilisateur.

Properties

Methods

__construct()

public __construct(EntityManagerInterface $entityManager, SerializerInterface $serializer) : mixed
Parameters
$entityManager : EntityManagerInterface

Gestionnaire d'entités Doctrine (injecté, non utilisé par les actions actuelles).

$serializer : SerializerInterface

Sérialiseur Symfony (injecté ; les charges utiles sont construites à la main).

list()

Retourne la liste paginée des paiements de l'utilisateur authentifié.

public list(Request $request, PaymentRepository $paymentRepository) : JsonResponse

Les résultats sont restreints à l'utilisateur courant et triés par created_at décroissant. Le paramètre page est ramené à 1 au minimum et limit est borné à l'intervalle [1, 50] (valeur par défaut 10) ; le filtre status n'est appliqué que s'il est fourni et non vide, sans validation de la valeur transmise. Le nombre total d'éléments est recalculé avec les mêmes critères pour produire le bloc de pagination. Pour chaque paiement, la commande liée est aplatie en un sous-objet, ou vaut null si aucune commande n'est rattachée.

Route : /api/payments (GET), nom api_payments_list. Requiert IS_AUTHENTICATED_FULLY.

Paramètres de requête : status (optionnel), page (optionnel, défaut 1), limit (optionnel, défaut 10, plafonné à 50).

Réponses : 200 liste renvoyée (éventuellement vide), 401 requête non authentifiée.

Parameters
$request : Request

Requête HTTP portant les paramètres de filtrage et de pagination.

$paymentRepository : PaymentRepository

Dépôt utilisé pour la recherche et le comptage.

Attributes
#[Get]
$path: '/api/payments'
$description: 'Récupère la liste des paiements de l\'utilisateur connecté'
$summary: 'Liste les paiements de l\'utilisateur'
$security: [['bearerAuth' => []]]
$tags: ['Payments']
$parameters: [new OA\Parameter(name: 'status', description: 'Filtrer par statut de paiement', in: 'query', required: false, schema: new OA\Schema(type: 'string', enum: ['pending', 'completed', 'failed', 'cancelled'])), new OA\Parameter(name: 'page', description: 'Numéro de page', in: 'query', required: false, schema: new OA\Schema(type: 'integer', default: 1)), new OA\Parameter(name: 'limit', description: 'Nombre d\'éléments par page', in: 'query', required: false, schema: new OA\Schema(type: 'integer', default: 10))]
$responses: [new OA\Response(response: 200, description: 'Liste des paiements récupérée avec succès', content: new OA\JsonContent(properties: [new OA\Property(property: 'payments', type: 'array', items: new OA\Items(properties: [new OA\Property(property: 'id', type: 'integer', example: 1), new OA\Property(property: 'amount', type: 'string', example: '99.99'), new OA\Property(property: 'currency', type: 'string', example: 'EUR'), new OA\Property(property: 'status', type: 'string', example: 'completed'), new OA\Property(property: 'payment_method', type: 'string', example: 'CREDIT_CART'), new OA\Property(property: 'stripe_payment_intent_id', type: 'string', example: 'pi_1234567890'), new OA\Property(property: 'created_at', type: 'string', format: 'date-time'), new OA\Property(property: 'order', properties: [new OA\Property(property: 'id', type: 'integer'), new OA\Property(property: 'total', type: 'string'), new OA\Property(property: 'status', type: 'string')], type: 'object')])), new OA\Property(property: 'pagination', properties: [new OA\Property(property: 'current_page', type: 'integer'), new OA\Property(property: 'total_pages', type: 'integer'), new OA\Property(property: 'total_items', type: 'integer'), new OA\Property(property: 'items_per_page', type: 'integer')], type: 'object')])), new OA\Response(response: 401, description: 'Non authentifié')]
#[IsGranted]
'IS_AUTHENTICATED_FULLY'
#[Route]
''
$name: 'list'
$methods: ['GET']
Return values
JsonResponse —

Objet JSON {payments: list<array<string, mixed>>, pagination: array<string, int>}.

show()

Retourne le détail d'un paiement.

public show(int $id, PaymentRepository $paymentRepository) : JsonResponse

Le paiement est chargé par sa clé primaire, puis un contrôle de propriété est effectué : seul le titulaire du paiement, ou un porteur de ROLE_ADMIN, peut le consulter. Le bloc order n'est construit que si une commande est rattachée ; la présence est testée via getOrders() alors que les valeurs sont lues via getOrder(), ce qui suppose que les deux accesseurs renvoient la même commande.

Attention : cette route est déclarée avant /stats et {id} n'est contraint par aucune exigence, elle capte donc aussi les segments non numériques.

Route : /api/payments/{id} (GET), nom api_payments_show. Requiert IS_AUTHENTICATED_FULLY.

Réponses : 200 paiement renvoyé, 403 paiement appartenant à un autre utilisateur (hors administrateur), 404 paiement inexistant, 401 requête non authentifiée.

Parameters
$id : int

Identifiant du paiement, issu du chemin.

$paymentRepository : PaymentRepository

Dépôt utilisé pour retrouver le paiement.

Attributes
#[Get]
$path: '/api/payments/{id}'
$summary: 'Récupère un paiement par son ID'
$description: 'Récupère les détails d\'un paiement spécifique'
$tags: ['Payments']
$security: [['bearerAuth' => []]]
$parameters: [new OA\Parameter(name: 'id', description: 'ID du paiement', in: 'path', required: true, schema: new OA\Schema(type: 'integer'))]
$responses: [new OA\Response(response: 200, description: 'Détails du paiement', content: new OA\JsonContent(properties: [new OA\Property(property: 'id', type: 'integer', example: 1), new OA\Property(property: 'amount', type: 'string', example: '99.99'), new OA\Property(property: 'currency', type: 'string', example: 'EUR'), new OA\Property(property: 'status', type: 'string', example: 'completed'), new OA\Property(property: 'payment_method', type: 'string', example: 'CREDIT_CART'), new OA\Property(property: 'stripe_payment_intent_id', type: 'string', example: 'pi_1234567890'), new OA\Property(property: 'created_at', type: 'string', format: 'date-time'), new OA\Property(property: 'order', type: 'object', properties: [new OA\Property(property: 'id', type: 'integer'), new OA\Property(property: 'firstname', type: 'string'), new OA\Property(property: 'lastname', type: 'string'), new OA\Property(property: 'email', type: 'string'), new OA\Property(property: 'total', type: 'string'), new OA\Property(property: 'status', type: 'string'), new OA\Property(property: 'created_at', type: 'string', format: 'date-time')])])), new OA\Response(response: 404, description: 'Paiement non trouvé'), new OA\Response(response: 403, description: 'Accès refusé')]
#[IsGranted]
'IS_AUTHENTICATED_FULLY'
#[Route]
'/{id}'
$name: 'show'
$methods: ['GET']
Return values
JsonResponse —

Objet JSON {id, amount, currency, status, payment_method, stripe_payment_intent_id, created_at, order} ou message d'erreur.

stats()

Retourne des statistiques agrégées sur les paiements de l'utilisateur.

public stats(Request $request, PaymentRepository $paymentRepository) : JsonResponse

La borne basse de la période est calculée à partir de l'instant courant : -1 week, -1 year, ou -1 month par défaut (toute valeur inconnue de period retombe sur le mois). Tous les paiements de l'utilisateur créés depuis cette borne sont chargés via un QueryBuilder, puis agrégés en PHP : montant cumulé, comptages par statut (completed, pending, et failed/cancelled fusionnés dans failed_payments) et montant moyen. Les montants sont formatés à deux décimales avec un point comme séparateur, sans séparateur de milliers. La valeur period renvoyée est celle reçue, même si elle n'a pas été reconnue.

Attention : la route /{id} étant déclarée avant celle-ci, ce point d'entrée peut être court-circuité par PaymentApiController::show() lors du routage.

Route : /api/payments/stats (GET), nom api_payments_stats. Requiert IS_AUTHENTICATED_FULLY.

Paramètres de requête : period (optionnel, week|month|year, défaut month).

Réponses : 200 systématiquement, 401 requête non authentifiée.

Parameters
$request : Request

Requête HTTP portant le paramètre period.

$paymentRepository : PaymentRepository

Dépôt utilisé pour construire la requête de période.

Attributes
#[Get]
$path: '/api/payments/stats'
$summary: 'Statistiques des paiements'
$description: 'Récupère les statistiques des paiements de l\'utilisateur'
$tags: ['Payments']
$security: [['bearerAuth' => []]]
$parameters: [new OA\Parameter(name: 'period', description: 'Période pour les statistiques', in: 'query', required: false, schema: new OA\Schema(type: 'string', enum: ['week', 'month', 'year'], default: 'month'))]
$responses: [new OA\Response(response: 200, description: 'Statistiques des paiements', content: new OA\JsonContent(properties: [new OA\Property(property: 'total_payments', type: 'integer', example: 25), new OA\Property(property: 'total_amount', type: 'string', example: '2499.75'), new OA\Property(property: 'completed_payments', type: 'integer', example: 23), new OA\Property(property: 'pending_payments', type: 'integer', example: 1), new OA\Property(property: 'failed_payments', type: 'integer', example: 1), new OA\Property(property: 'average_amount', type: 'string', example: '99.99'), new OA\Property(property: 'period', type: 'string', example: 'month')])), new OA\Response(response: 401, description: 'Non authentifié')]
#[IsGranted]
'IS_AUTHENTICATED_FULLY'
#[Route]
'/stats'
$name: 'stats'
$methods: ['GET']
Return values
JsonResponse —

Objet JSON {total_payments, total_amount, completed_payments, pending_payments, failed_payments, average_amount, period}.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results