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 :
- Vous souhaitez débiter uniquement après la livraison.
- Vous risquez de capturer moins que le montant autorisé (articles en rupture, commandes ajustées).
- 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"
}
}
}'const res = await fetch("https://sandbox.cardencer.com/payments", {
method: "POST",
headers: { "api-key": process.env.CARDENCER_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
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" },
},
}),
});
const payment = await res.json(); // payment.status === "requires_capture"payment = requests.post(
"https://sandbox.cardencer.com/payments",
headers={"api-key": os.environ["CARDENCER_API_KEY"]},
json={
"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"}},
},
).json() # payment["status"] == "requires_capture"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 }'const res = await fetch(`https://sandbox.cardencer.com/payments/${paymentId}/capture`, {
method: "POST",
headers: { "api-key": process.env.CARDENCER_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ amount_to_capture: 6540 }),
});requests.post(
f"https://sandbox.cardencer.com/payments/{payment_id}/capture",
headers={"api-key": os.environ["CARDENCER_API_KEY"]},
json={"amount_to_capture": 6540},
)Règles :
amount_to_capturedoit être supérieur à zéro et ne pas dépasseramount_capturable.- Avec
manual_multiple,amount_to_captureest obligatoire à chaque appel. - L'endpoint accepte les paiements en
requires_capture,partially_captured_and_capturableoupartially_authorized_and_requires_capture, ainsi qu'enprocessingpourmanual_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.