Aller au contenu

Capture manuelle

Bloquez les fonds sur la carte de votre client et capturez-les plus tard, en totalité ou en partie, en une ou plusieurs fois.

Avec la capture manuelle, l'autorisation bloque les fonds du client et vous les capturez plus tard, une fois les marchandises expédiées ou le service rendu. On parle aussi d'autorisation puis capture, ou de flux en deux étapes.

Utilisez-la lorsque :

  1. Vous souhaitez débiter uniquement après la livraison.
  2. Vous risquez de capturer moins que le montant autorisé (articles en rupture, commandes ajustées).
  3. Le client doit voir un débit correspondant à ce qu'il a réellement reçu.

Choisissez une méthode de capture avant l'autorisation#

capture_method est défini à la création du paiement et ne peut plus être modifié après l'autorisation.

capture_method Effet
automatic Par défaut. Autorisation et capture simultanées. L'endpoint de capture rejette ces paiements.
manual Une seule capture : la totalité du montant bloqué ou une partie, en une fois.
manual_multiple Plusieurs captures sur une même autorisation, dans la limite du montant autorisé.

Choisissez manual_multiple si vous êtes susceptible d'expédier en plusieurs colis. Avec manual, tout ce que vous ne prélevez pas lors de l'unique capture n'est plus capturable.

1. Créez le paiement avec capture différée#

Définissez "capture_method": "manual". Ici, le paiement est également confirmé depuis le serveur avec une carte de test ; avec le SDK de paiement, omettez confirm et payment_method_data et laissez le SDK confirmer.

curl https://sandbox.cardencer.com/payments \
  -H "api-key: $CARDENCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 6540,
    "currency": "EUR",
    "confirm": true,
    "capture_method": "manual",
    "description": "Order 58212",
    "return_url": "https://example.com/checkout/complete",
    "payment_method": "card",
    "payment_method_type": "credit",
    "payment_method_data": {
      "card": {
        "card_number": "4242424242424242",
        "card_exp_month": "12",
        "card_exp_year": "2030",
        "card_holder_name": "Test Customer",
        "card_cvc": "123"
      }
    }
  }'

Si l'autorisation aboutit, le paiement passe en requires_capture et amount_capturable est égal au montant autorisé. Indiquez au client que ses fonds sont bloqués et qu'ils seront débités à l'expédition.

2. Capturez#

Appelez POST /payments/{payment_id}/capture. Omettez amount_to_capture pour capturer la totalité du montant capturable, ou indiquez un montant inférieur.

curl https://sandbox.cardencer.com/payments/pay_mbabizu24mvu3mela5njyhpit4/capture \
  -H "api-key: $CARDENCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_to_capture": 6540 }'

Règles :

  • amount_to_capture doit être supérieur à zéro et ne pas dépasser amount_capturable.
  • Avec manual_multiple, amount_to_capture est obligatoire à chaque appel.
  • L'endpoint accepte les paiements en requires_capture, partially_captured_and_capturable ou partially_authorized_and_requires_capture, ainsi qu'en processing pour manual_multiple.

3. Ou annulez l'autorisation#

Si la commande ne sera pas expédiée, libérez les fonds bloqués au lieu de les capturer :

curl https://sandbox.cardencer.com/payments/pay_mbabizu24mvu3mela5njyhpit4/cancel \
  -H "api-key: $CARDENCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cancellation_reason": "out_of_stock" }'

Le paiement passe en cancelled.

Que devient le montant non capturé ?#

manual : une capture clôt le paiement. Si vous capturez le montant total, il passe en succeeded. Si vous capturez moins, il passe en partially_captured, amount_capturable tombe à 0 et le reste du montant bloqué ne peut plus être capturé. Le délai de disparition du blocage restant sur le relevé du client dépend de son émetteur.

manual_multiple : chaque capture qui n'épuise pas le montant bloqué laisse le paiement en partially_captured_and_capturable, le reliquat restant capturable. Lorsque le total des captures atteint le montant autorisé, le paiement passe en succeeded.

amount_captured reflète ce que vous avez effectivement prélevé et constitue le plafond des remboursements. Un paiement n'est remboursable qu'une fois en succeeded ou partially_captured.

Statuts#

Statut Signification
requires_capture Autorisé. La totalité du montant est capturable.
succeeded Tout le montant capturable a été capturé. Statut final.
partially_captured Capture partielle, plus rien à capturer. Statut final. Remboursable jusqu'à amount_captured.
partially_captured_and_capturable Capture partielle, reliquat encore capturable. Pas encore remboursable.
processing Une capture manual_multiple est en cours.
partially_authorized_and_requires_capture L'émetteur a autorisé moins que le montant demandé. Capturez sur la base du montant réduit.
cancelled Annulé avant toute capture.

Les autorisations ne sont pas éternelles. La plupart expirent au bout d'environ 7 jours, selon le réseau de carte et l'émetteur. Capturez dès l'expédition.