Requêtes de statut

Chaque paiement dans Cost+ est représenté par une commande contenant une ou plusieurs transactions. Vous pouvez vérifier le statut actuel de toute commande en interrogeant l'API, soit par polling, soit en vous appuyant sur les webhooks.

Récupérer le statut d'une commande

Envoyez une requête GET à /v1/orders/\{id\}/ pour récupérer l'objet commande complet, y compris son statut actuel et toutes les transactions associées.

GET /v1/orders/b9ae6.../

Bien que le polling fonctionne pour vérifier le statut d'une commande, les webhooks sont l'approche recommandée pour les intégrations en production. Ils fournissent des notifications en temps réel sans la surcharge d'appels API répétés.

Statuts des commandes

Une commande progresse à travers les statuts suivants :

Statut	Final	Description
`new`	Non	La commande vient d'être créée. Aucune tentative de paiement n'a encore été effectuée.
`processing`	Non	Une tentative de paiement est en cours. Le client peut être en train de compléter la vérification 3D Secure ou une autre étape de vérification.
`error`	Non	La tentative de paiement a échoué. Le client peut réessayer avec la même méthode de paiement ou une autre.
`completed`	Oui	Le paiement a réussi. Vous pouvez traiter la commande.
`cancelled`	Oui	La commande a été annulée, soit par le client, soit via l'API.
`expired`	Oui	La commande a expiré avant qu'un paiement réussi ne soit effectué. La période d'expiration par défaut est de 30 minutes.

Seuls les statuts marqués Final = Oui sont terminaux. Les commandes en statut new, processing ou error peuvent encore passer à completed.

Exemple : Commande en cours de traitement

Lorsqu'un client a initié un paiement mais qu'il n'est pas encore finalisé :

{
  "id": "b9ae6...",
  "project_id": "proj_abc123",
  "merchant_order_id": "my-order-id-1",
  "created": "2024-01-01T12:00:00.000000+00:00",
  "modified": "2024-01-01T12:01:30.000000+00:00",
  "completed": null,
  "expiration_period": "PT30M",
  "status": "processing",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "payment_url": "https://pay.costplus.com/...",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "id": "txn_001...",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "status": "processing",
      "amount": 1295,
      "currency": "EUR"
    }
  ],
  "flags": ["is-test"]
}

Exemple : Commande finalisée

Une fois le paiement réussi, la commande atteint le statut completed :

{
  "id": "b9ae6...",
  "project_id": "proj_abc123",
  "merchant_order_id": "my-order-id-1",
  "created": "2024-01-01T12:00:00.000000+00:00",
  "modified": "2024-01-01T12:02:15.000000+00:00",
  "completed": "2024-01-01T12:02:15.000000+00:00",
  "expiration_period": "PT30M",
  "status": "completed",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "payment_url": "https://pay.costplus.com/...",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "id": "txn_001...",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "payment_method_details": {
        "card_last_four": "4242",
        "card_expiry_month": 12,
        "card_expiry_year": 2026,
        "card_holder_name": "J. Smith"
      },
      "status": "completed",
      "amount": 1295,
      "currency": "EUR"
    }
  ],
  "flags": ["is-test"]
}

Détails des transactions

Chaque transaction au sein d'une commande contient les champs clés suivants :

Champ	Description
`payment_method`	La méthode de paiement utilisée (ex. `credit-card`, `ideal`, `apple-pay`)
`payment_method_brand`	La marque ou l'émetteur (ex. `visa`, `mastercard`, `amex`)
`payment_method_details`	Un objet contenant les détails spécifiques à la méthode, tels que les quatre derniers chiffres de la carte, la date d'expiration et le nom du titulaire
`status`	Le statut de cette transaction spécifique
`amount`	Le montant de la transaction en centimes
`currency`	La devise de la transaction

Ne vous fiez pas uniquement à la redirection du client vers votre return_url comme confirmation de paiement. Vérifiez toujours le statut de la commande via l'API ou un webhook avant de traiter une commande.

Points d'accès associés

Obtenir une commande — récupérer l'objet commande complet et son statut actuel
Lister les commandes — lister les commandes avec filtrage par plage de dates