DocsAutorizzazioni, Catture e Annullamenti
Gestisci i flussi di autorizzazione, cattura e annullamento dei pagamenti
Alcuni metodi di pagamento supportano un flusso in due fasi: prima autorizzare (riservare i fondi), poi catturare (incassare i fondi) o annullare (rilasciare la riserva).
Modalità di Cattura
Imposta capture_mode sull'ordine per controllare quando i fondi vengono catturati:
| Modalità | Comportamento |
|---|---|
manual | Catturi esplicitamente quando sei pronto (es. dopo la spedizione). Se non catturi prima della scadenza dell'ordine, l'autorizzazione viene persa e non può essere catturata. |
delayed | I fondi vengono catturati automaticamente al momento della scadenza dell'expiration_period. |
{
"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"
}
]
}Con la cattura manual, devi catturare prima che scada il periodo di scadenza dell'ordine. Una volta scaduto, l'autorizzazione viene rilasciata e i fondi non possono essere catturati. Imposta un expiration_period appropriato per i tuoi tempi di evasione.
Puoi impostare capture_mode a livello di ordine senza specificare transactions. La pagina di pagamento ospitata mostrerà quindi solo i metodi di pagamento che supportano la modalità di cattura specificata.
Verificare gli Importi Catturabili
Prima di catturare, puoi verificare quanto è disponibile per la cattura richiedendo amount_details:
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"La risposta include un oggetto amount_details:
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Righe dell'Ordine
Quando si utilizzano catture e annullamenti per riga dell'ordine, usa questi tipi:
| Tipo | Descrizione |
|---|---|
physical | Prodotto fisico |
discount | Importo dello sconto |
shipping_fee | Costo di spedizione |
sales_tax | Imposta sulle vendite |
digital | Prodotto digitale |
gift_card | Carta regalo |
store_credit | Credito del negozio |
surcharge | Supplemento |
Cattura dei Pagamenti
Cattura per Riga dell'Ordine
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Cattura per Importo
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Annullamento dei Pagamenti
L'annullamento rilascia i fondi autorizzati al cliente.
Annullamento per Riga dell'Ordine
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Annullamento per Importo
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Parametri di Query
Aggiungi parametri di query per includere dettagli aggiuntivi nella risposta:
| Parametro | Descrizione |
|---|---|
?fields[]=order_line_details | Include il dettaglio delle righe dell'ordine |
?fields[]=amount_details | Include il dettaglio degli importi |
Blocco Ottimistico
Gli endpoint di cattura e annullamento supportano il blocco ottimistico basato su ETag tramite l'header if-match. Questo previene condizioni di concorrenza quando più sistemi tentano di catturare la stessa transazione.
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}'Se l'ETag non corrisponde (l'ordine è stato modificato dall'ultimo recupero), riceverai una risposta 412 Precondition Failed.
Cost+ supporta una cattura per autorizzazione, e gli annullamenti possono essere elaborati solo prima di qualsiasi cattura. Pianifica la tua strategia di cattura di conseguenza.
Endpoint Correlati
- Cattura per Importo — cattura un importo specifico da un ordine autorizzato
- Cattura per Riga dell'Ordine — cattura righe specifiche dell'ordine
- Annullamento per Importo — annulla un importo specifico da un ordine autorizzato
- Annullamento per Riga dell'Ordine — annulla righe specifiche dell'ordine