DocsAutorisations, captures et annulations
Gérer les flux d'autorisation, de capture et d'annulation de paiement
Certaines méthodes de paiement prennent en charge un flux en deux étapes : d'abord autoriser (réserver les fonds), puis capturer (encaisser les fonds) ou annuler (libérer la réservation).
Modes de capture
Définissez capture_mode sur la commande pour contrôler quand les fonds sont capturés :
| Mode | Comportement |
|---|---|
manual | Vous capturez explicitement quand vous êtes prêt (ex. après l'expédition). Si vous ne capturez pas avant l'expiration de la commande, l'autorisation est perdue et ne peut plus être capturée. |
delayed | Les fonds sont automatiquement capturés au moment où la période d'expiration (expiration_period) s'écoule. |
{
"currency": "EUR",
"amount": 5000,
"capture_mode": "manual",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook",
"transactions": [
{
"payment_method": "credit-card"
}
]
}Avec la capture manual, vous devez capturer avant la fin de la période d'expiration de la commande. Une fois expirée, l'autorisation est libérée et les fonds ne peuvent plus être capturés. Définissez une expiration_period appropriée pour votre délai de traitement.
Vous pouvez définir capture_mode au niveau de la commande sans spécifier transactions. La page de paiement hébergée n'affichera alors que les méthodes de paiement prenant en charge le mode de capture spécifié.
Vérifier les montants capturables
Avant de capturer, vous pouvez vérifier le montant disponible pour la capture en demandant amount_details :
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"La réponse inclut un objet amount_details :
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Lignes de commande
Lors de l'utilisation des captures et annulations par ligne de commande, utilisez ces types :
| Type | Description |
|---|---|
physical | Produit physique |
discount | Montant de réduction |
shipping_fee | Frais de livraison |
sales_tax | Taxe de vente |
digital | Produit numérique |
gift_card | Carte cadeau |
store_credit | Crédit en magasin |
surcharge | Supplément |
Capturer des paiements
Capture par ligne de commande
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Capture par montant
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Annuler des paiements
L'annulation libère les fonds autorisés et les restitue au client.
Annulation par ligne de commande
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Annulation par montant
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Paramètres de requête
Ajoutez des paramètres de requête pour inclure des détails supplémentaires dans la réponse :
| Paramètre | Description |
|---|---|
?fields[]=order_line_details | Inclure le détail des lignes de commande |
?fields[]=amount_details | Inclure le détail des montants |
Verrouillage optimiste
Les points d'accès de capture et d'annulation prennent en charge le verrouillage optimiste basé sur ETag via l'en-tête if-match. Cela évite les conditions de concurrence lorsque plusieurs systèmes tentent de capturer la même transaction.
curl -X POST https://api.costplus.online/v1/orders/{id}/transactions/{tid}/captures/amount \
-u {api_key}: \
-H "Content-Type: application/json" \
-H "if-match: \"etag-value\"" \
-d '{"description": "Capture", "amount": 2500}'Si l'ETag ne correspond pas (la commande a été modifiée depuis votre dernière récupération), vous recevrez une réponse 412 Precondition Failed.
Cost+ prend en charge une seule capture par autorisation, et les annulations ne peuvent être traitées qu'avant toute capture. Planifiez votre stratégie de capture en conséquence.
Points d'accès associés
- Capture par montant — capturer un montant spécifique d'une commande autorisée
- Capture par ligne de commande — capturer des lignes de commande spécifiques
- Annulation par montant — annuler un montant spécifique d'une commande autorisée
- Annulation par ligne de commande — annuler des lignes de commande spécifiques