DocsΕξουσιοδοτήσεις, Δεσμεύσεις & Ακυρώσεις
Διαχείριση ροών εξουσιοδότησης, δέσμευσης και ακύρωσης πληρωμής
Ορισμένες μέθοδοι πληρωμής υποστηρίζουν ροή δύο βημάτων: πρώτα εξουσιοδότηση (δέσμευση κεφαλαίων), στη συνέχεια δέσμευση (είσπραξη κεφαλαίων) ή ακύρωση (αποδέσμευση της δέσμευσης).
Λειτουργίες Δέσμευσης
Ορίστε capture_mode στην παραγγελία για να ελέγξετε πότε δεσμεύονται τα κεφάλαια:
| Λειτουργία | Συμπεριφορά |
|---|---|
manual | Δεσμεύετε ρητά όταν είστε έτοιμοι (π.χ., μετά την αποστολή). Αν δεν δεσμεύσετε πριν λήξει η παραγγελία, η εξουσιοδότηση χάνεται και δεν μπορεί να δεσμευτεί. |
delayed | Τα κεφάλαια δεσμεύονται αυτόματα τη στιγμή που παρέρχεται η 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"
}
]
}Με manual δέσμευση, πρέπει να δεσμεύσετε πριν λήξει η περίοδος λήξης της παραγγελίας. Μόλις λήξει, η εξουσιοδότηση αποδεσμεύεται και τα κεφάλαια δεν μπορούν να δεσμευτούν. Ορίστε μια κατάλληλη expiration_period για το χρονοδιάγραμμα εκπλήρωσής σας.
Μπορείτε να ορίσετε capture_mode σε επίπεδο παραγγελίας χωρίς να καθορίσετε transactions. Η φιλοξενούμενη σελίδα πληρωμής τότε θα εμφανίζει μόνο μεθόδους πληρωμής που υποστηρίζουν τη συγκεκριμένη λειτουργία δέσμευσης.
Έλεγχος Ποσών Διαθέσιμων για Δέσμευση
Πριν τη δέσμευση, μπορείτε να ελέγξετε πόσο είναι διαθέσιμο για δέσμευση ζητώντας amount_details:
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"Η απόκριση περιλαμβάνει ένα αντικείμενο amount_details:
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Γραμμές Παραγγελίας
Όταν χρησιμοποιείτε δεσμεύσεις και ακυρώσεις ανά γραμμή παραγγελίας, χρησιμοποιήστε αυτούς τους τύπους:
| Τύπος | Περιγραφή |
|---|---|
physical | Φυσικό προϊόν |
discount | Ποσό έκπτωσης |
shipping_fee | Κόστος αποστολής |
sales_tax | Φόρος πωλήσεων |
digital | Ψηφιακό προϊόν |
gift_card | Δωροκάρτα |
store_credit | Πίστωση καταστήματος |
surcharge | Επιβάρυνση |
Δέσμευση Πληρωμών
Δέσμευση ανά Γραμμή Παραγγελίας
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Δέσμευση ανά Ποσό
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Ακύρωση Πληρωμών
Η ακύρωση αποδεσμεύει τα εξουσιοδοτημένα κεφάλαια πίσω στον πελάτη.
Ακύρωση ανά Γραμμή Παραγγελίας
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Ακύρωση ανά Ποσό
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Παράμετροι Ερωτήματος
Προσθέστε παραμέτρους ερωτήματος για να συμπεριλάβετε πρόσθετες λεπτομέρειες στην απόκριση:
| Παράμετρος | Περιγραφή |
|---|---|
?fields[]=order_line_details | Συμπερίληψη ανάλυσης γραμμών παραγγελίας |
?fields[]=amount_details | Συμπερίληψη ανάλυσης ποσών |
Αισιόδοξο Κλείδωμα
Τα endpoints δέσμευσης και ακύρωσης υποστηρίζουν αισιόδοξο κλείδωμα βασισμένο σε ETag μέσω της κεφαλίδας if-match. Αυτό αποτρέπει συνθήκες ανταγωνισμού όταν πολλαπλά συστήματα προσπαθούν να δεσμεύσουν την ίδια συναλλαγή.
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}'Αν το ETag δεν ταιριάζει (η παραγγελία τροποποιήθηκε από την τελευταία φορά που την ανακτήσατε), θα λάβετε απόκριση 412 Precondition Failed.
Η Cost+ υποστηρίζει μία δέσμευση ανά εξουσιοδότηση, και οι ακυρώσεις μπορούν να γίνουν μόνο πριν από οποιαδήποτε δέσμευση. Σχεδιάστε τη στρατηγική δέσμευσής σας ανάλογα.
Σχετικά Endpoints
- Δέσμευση ανά Ποσό — δέσμευση συγκεκριμένου ποσού από εξουσιοδοτημένη παραγγελία
- Δέσμευση ανά Γραμμή Παραγγελίας — δέσμευση συγκεκριμένων γραμμών παραγγελίας
- Ακύρωση ανά Ποσό — ακύρωση συγκεκριμένου ποσού από εξουσιοδοτημένη παραγγελία
- Ακύρωση ανά Γραμμή Παραγγελίας — ακύρωση συγκεκριμένων γραμμών παραγγελίας