Démarrage rapide

Ce guide vous accompagne dans la création et la finalisation d'un paiement de test avec l'API Cost+. À la fin, vous disposerez d'une intégration fonctionnelle sur laquelle vous pourrez vous appuyer.

Prérequis

• Un compte Cost+ avec un site web sandbox — créez-en un dans le Portail marchand
• Votre clé API sandbox (accessible sous Sites web → votre site web sandbox → Intégration)

Étape 1 : Créer une commande

Envoyez une requête POST pour créer une commande de paiement. Remplacez YOUR_API_KEY par votre clé API sandbox :

curl -X POST https://api.costplus.online/v1/orders/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "amount": 1295,
    "merchant_order_id": "my-first-order",
    "description": "Test order",
    "return_url": "https://example.com/return",
    "webhook_url": "https://example.com/webhook",
    "transactions": [
      {
        "payment_method": "credit-card"
      }
    ]
  }'

L'API renvoie l'objet commande complet. Les champs clés sont id, status et le payment_url à l'intérieur de la transaction :

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "description": "Test order",
  "return_url": "https://example.com/return",
  "webhook_url": "https://example.com/webhook",
  "created": "2026-01-15T12:00:05.433502+00:00",
  "modified": "2026-01-15T12:00:05.553125+00:00",
  "expiration_period": "PT1H",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "new",
      "amount": 1295,
      "currency": "EUR",
      "payment_url": "https://pay.costplus.online/4851e31c.../credit-card/d291f03f...",
      "is_capturable": false,
      "expiration_period": "PT30M"
    }
  ]
}

Sauvegardez l'id — vous en aurez besoin à l'étape 3.

Étape 2 : Finaliser le paiement de test

1. Ouvrez le payment_url de la réponse dans votre navigateur
2. Sur la page de paiement, saisissez les informations de la carte de test :

3. Validez le paiement
4. Vous serez redirigé vers votre return_url

Étape 3 : Vérifier le paiement

Récupérez la commande pour confirmer qu'elle a abouti :

curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/

Un paiement réussi ressemble à ceci :

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "completed",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "completed": "2026-01-15T12:02:30.123456+00:00",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "completed",
      "amount": 1295,
      "currency": "EUR",
      "payment_method_details": {
        "truncated_pan": "1111",
        "card_expiry": "122028"
      }
    }
  ]
}

Le status de la commande est "completed" — le paiement a réussi.

Étape 4 : Gérer le webhook (recommandé)

Lorsque le statut du paiement change, Cost+ envoie une requête POST à votre webhook_url :

{
  "event": "status_changed",
  "order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}

À la réception :

1. Appelez GET /v1/orders/{order_id}/ pour vérifier le statut actuel (ne faites jamais confiance au payload du webhook seul)
2. Renvoyez un HTTP 200 pour confirmer la réception
3. Traitez la commande si le statut est "completed"

Consultez le guide Webhooks pour la logique de réessai, les bonnes pratiques et les détails du payload.

Alternative : Liens de paiement

Si vous n'avez pas besoin de logique de redirection côté serveur, les liens de paiement offrent un chemin plus simple. Créez un lien, partagez l'URL avec votre client, et vérifiez le statut plus tard.

curl -X POST https://api.costplus.online/v1/paymentlinks/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "invoice-1234",
    "amount": 2500,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

La réponse inclut un payment_url que vous pouvez partager par e-mail, SMS ou messagerie. Le client peut tenter le paiement plusieurs fois (jusqu'à 25) jusqu'à l'expiration du lien ou la réussite du paiement.

Consultez le guide Liens de paiement pour le flux complet.

Et ensuite ?

Vous avez finalisé votre premier paiement. Voici les prochaines étapes :

• Page de paiement hébergée — référence complète HPP avec tous les champs et options de requête
• Paiements récurrents — mettre en place des abonnements et la facturation planifiée
• Paiements en un clic — paiement rapide pour les clients récurrents
• Autorisation / Capture / Annulation — autoriser d'abord, capturer ensuite (ex. à l'expédition)
• Remboursements — traiter les remboursements totaux et partiels
• SDKs — bibliothèques officielles pour Node.js, Python, PHP, Java/Kotlin, C#/.NET et Ruby
• Plugins — intégrations prêtes à l'emploi pour Shopify, WooCommerce, Magento et plus

Points d'accès associés

• Créer une commande — référence API complète pour la création de commande
• Obtenir une commande — récupérer les détails et le statut d'une commande
• Créer un lien de paiement — créer des liens de paiement réutilisables