Σύνδεσμοι Πληρωμής

Δημιουργία επαναχρησιμοποιήσιμων συνδέσμων πληρωμής

Οι σύνδεσμοι πληρωμής είναι επαναχρησιμοποιήσιμα URL που επιτρέπουν στους πελάτες να πληρώσουν για μια παραγγελία. Σε αντίθεση με τις τυπικές παραγγελίες που λήγουν μετά από μία αποτυχημένη προσπάθεια, οι σύνδεσμοι πληρωμής υποστηρίζουν πολλαπλές προσπάθειες, καθιστώντας τους ιδανικούς για τιμολόγια, πληρωμές μέσω email και σενάρια όπου ο πελάτης μπορεί να μην πληρώσει αμέσως.

Βασικά Χαρακτηριστικά

Επαναχρησιμοποιήσιμοι: Οι πελάτες μπορούν να επαναπροσπαθήσουν πληρωμή έως 25 φορές αν οι προηγούμενες προσπάθειες αποτύχουν.
Μεγάλης διάρκειας: Η προεπιλεγμένη λήξη είναι 30 ημέρες (ρυθμιζόμενο μέσω expiration_period).
Διαμοιραζόμενοι: Στείλτε τον σύνδεσμο μέσω email, SMS, chat ή ενσωματώστε τον στον ιστότοπό σας.

Δημιουργία Συνδέσμου Πληρωμής

Στείλτε ένα αίτημα POST στο /v1/paymentlinks/:

POST /v1/paymentlinks/

curl -X POST https://api.costplus.online/v1/paymentlinks/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "invoice-1234",
    "amount": 995,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

Η απόκριση περιλαμβάνει το payment_url για κοινοποίηση στον πελάτη και ένα μοναδικό id για παρακολούθηση:

Response (201 Created)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "new",
  "reason": "Payment Link was created, not yet visited",
  "orders": {},
  "created": "2026-01-15T12:00:00.000000Z"
}

Αποθηκεύστε το id — θα το χρησιμοποιήσετε για να ελέγξετε την κατάσταση του συνδέσμου πληρωμής αργότερα.

Απαιτούμενα Πεδία

Πεδίο	Περιγραφή
`merchant_order_id`	Το δικό σας αναγνωριστικό αναφοράς για τον σύνδεσμο πληρωμής
`amount`	Ποσό σε λεπτά (π.χ., 9,95 EUR = `995`)
`currency`	Κωδικός νομίσματος ISO 4217 (π.χ., `EUR`, `GBP`)

Προαιρετικά Πεδία

Πεδίο	Περιγραφή
`description`	Περιγραφή που εμφανίζεται στον πελάτη
`expiration_period`	Διάρκεια ISO 8601. Προεπιλογή `P30D` (30 ημέρες)
`return_url`	URL ανακατεύθυνσης πελάτη μετά από επιτυχή πληρωμή
`failure_url`	URL ανακατεύθυνσης πελάτη σε ακύρωση, λήξη ή σφάλμα
`webhook_url`	URL για λήψη ειδοποιήσεων αλλαγής κατάστασης
`customer`	Αντικείμενο στοιχείων πελάτη (όνομα, email, κ.λπ.)

Αν παρέχετε τόσο return_url όσο και failure_url, οι πελάτες ανακατευθύνονται στο failure_url όταν η κατάσταση παραγγελίας είναι cancelled, expired ή error. Διαφορετικά, όλες οι ανακατευθύνσεις πηγαίνουν στο return_url.

Ανάκτηση Συνδέσμου Πληρωμής

Στείλτε ένα αίτημα GET στο /v1/paymentlinks/{id}/ χρησιμοποιώντας το id του συνδέσμου πληρωμής από την απόκριση δημιουργίας:

GET /v1/paymentlinks/{id}/

curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/paymentlinks/e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1/

Η απόκριση περιλαμβάνει την τρέχουσα κατάσταση και αναφορές σε όλες τις παραγγελίες που δημιουργήθηκαν από τον σύνδεσμο, ομαδοποιημένες κατά κατάσταση:

Response (completed example)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "completed",
  "reason": "Completed",
  "completed": "2026-01-15T12:05:30.123456+00:00",
  "completed_order_id": "3bb663cc-2a20-400d-8bf6-18d9695d0c66",
  "orders": {
    "error": ["0d79014c-0aaa-4fd6-87c5-c8cfa5f5ac69"],
    "completed": ["3bb663cc-2a20-400d-8bf6-18d9695d0c66"]
  }
}

Σε αυτό το παράδειγμα, ο πελάτης έκανε μία αποτυχημένη προσπάθεια (παραγγελία 0d79014c... σε κατάσταση error) πριν πετύχει (παραγγελία 3bb663cc... σε κατάσταση completed). Μπορείτε να ανακτήσετε πλήρεις λεπτομέρειες οποιασδήποτε παραγγελίας μέσω GET /v1/orders/{order_id}/.

Καταστάσεις Συνδέσμων Πληρωμής

Κατάσταση	Περιγραφή
`new`	Ο σύνδεσμος δημιουργήθηκε αλλά δεν έχει γίνει καμία προσπάθεια πληρωμής.
`processing`	Μια προσπάθεια πληρωμής βρίσκεται σε εξέλιξη.
`all_unsuccessful`	Όλες οι προσπάθειες πληρωμής μέχρι στιγμής έχουν αποτύχει. Ο πελάτης μπορεί ακόμα να επαναπροσπαθήσει (έως 25 προσπάθειες).
`completed`	Η πληρωμή ήταν επιτυχής. Ο σύνδεσμος δεν είναι πλέον ενεργός.
`expired`	Ο σύνδεσμος έχει λήξει πριν γίνει επιτυχής πληρωμή.

Η κατάσταση all_unsuccessful δεν είναι τελική. Ο πελάτης μπορεί ακόμα να προσπαθήσει να πληρώσει μέχρι είτε η πληρωμή να πετύχει, να φτάσει ο μέγιστος αριθμός προσπαθειών (25), ή ο σύνδεσμος να λήξει.

Μόλις ένας σύνδεσμος πληρωμής φτάσει σε κατάσταση completed ή expired, δεν μπορεί να χρησιμοποιηθεί ξανά. Δημιουργήστε νέο σύνδεσμο πληρωμής αν ο πελάτης χρειάζεται να πληρώσει ξανά.

Παράδειγμα Ροής Εργασίας

Δημιουργήστε σύνδεσμο πληρωμής μέσω POST /v1/paymentlinks/.
Μοιραστείτε το payment_url που επιστράφηκε με τον πελάτη σας (π.χ., μέσω email, SMS ή τιμολογίου).
Ο πελάτης ανοίγει τον σύνδεσμο και ολοκληρώνει την πληρωμή.
Η Cost+ στέλνει webhook στο webhook_url σας όταν αλλάξει η κατάσταση.
Επαληθεύστε την κατάσταση συνδέσμου πληρωμής μέσω GET /v1/paymentlinks/{id}/.
Εκτελέστε την παραγγελία μόλις η κατάσταση είναι completed.

Σχετικά Endpoints

Δημιουργία Συνδέσμου Πληρωμής — δημιουργία επαναχρησιμοποιήσιμου συνδέσμου πληρωμής
Λήψη Συνδέσμου Πληρωμής — ανάκτηση τρέχουσας κατάστασης ενός συνδέσμου πληρωμής

Σύνδεσμοι Πληρωμής

On this page