Γρήγορη Εκκίνηση

Αυτός ο οδηγός σας καθοδηγεί στη δημιουργία και ολοκλήρωση μιας δοκιμαστικής πληρωμής χρησιμοποιώντας το API της Cost+. Στο τέλος, θα έχετε μια λειτουργική ενσωμάτωση πάνω στην οποία μπορείτε να χτίσετε.

Προαπαιτούμενα

• Ένας λογαριασμός Cost+ με ιστοσελίδα sandbox — δημιουργήστε μία στην Πύλη Εμπόρου
• Το κλειδί API sandbox σας (βρίσκεται στα Websites → η ιστοσελίδα sandbox σας → Integration)

Βήμα 1: Δημιουργία Παραγγελίας

Στείλτε ένα αίτημα POST για να δημιουργήσετε μια παραγγελία πληρωμής. Αντικαταστήστε το YOUR_API_KEY με το κλειδί API sandbox σας:

curl -X POST https://api.costplus.online/v1/orders/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "amount": 1295,
    "merchant_order_id": "my-first-order",
    "description": "Test order",
    "return_url": "https://example.com/return",
    "webhook_url": "https://example.com/webhook",
    "transactions": [
      {
        "payment_method": "credit-card"
      }
    ]
  }'

Το API επιστρέφει το πλήρες αντικείμενο παραγγελίας. Τα βασικά πεδία είναι id, status και το payment_url μέσα στη συναλλαγή:

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "description": "Test order",
  "return_url": "https://example.com/return",
  "webhook_url": "https://example.com/webhook",
  "created": "2026-01-15T12:00:05.433502+00:00",
  "modified": "2026-01-15T12:00:05.553125+00:00",
  "expiration_period": "PT1H",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "new",
      "amount": 1295,
      "currency": "EUR",
      "payment_url": "https://pay.costplus.online/4851e31c.../credit-card/d291f03f...",
      "is_capturable": false,
      "expiration_period": "PT30M"
    }
  ]
}

Αποθηκεύστε το id — θα το χρειαστείτε στο Βήμα 3.

Βήμα 2: Ολοκλήρωση της Δοκιμαστικής Πληρωμής

1. Ανοίξτε το payment_url από την απόκριση στον περιηγητή σας
2. Στη σελίδα πληρωμής, εισάγετε τα στοιχεία δοκιμαστικής κάρτας:

3. Υποβάλετε την πληρωμή
4. Θα ανακατευθυνθείτε πίσω στο return_url σας

Βήμα 3: Επαλήθευση της Πληρωμής

Ανακτήστε την παραγγελία για να επιβεβαιώσετε ότι ολοκληρώθηκε:

curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/

Μια επιτυχημένη πληρωμή φαίνεται έτσι:

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "completed",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "completed": "2026-01-15T12:02:30.123456+00:00",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "completed",
      "amount": 1295,
      "currency": "EUR",
      "payment_method_details": {
        "truncated_pan": "1111",
        "card_expiry": "122028"
      }
    }
  ]
}

Η κατάσταση παραγγελίας status είναι "completed" — η πληρωμή ήταν επιτυχής.

Βήμα 4: Διαχείριση του Webhook (Συνιστάται)

Όταν η κατάσταση πληρωμής αλλάξει, η Cost+ στέλνει ένα αίτημα POST στο webhook_url σας:

{
  "event": "status_changed",
  "order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}

Όταν το λάβετε:

1. Καλέστε GET /v1/orders/{order_id}/ για να επαληθεύσετε την τρέχουσα κατάσταση (μην εμπιστεύεστε ποτέ μόνο το payload του webhook)
2. Επιστρέψτε HTTP 200 για επιβεβαίωση λήψης
3. Εκτελέστε την παραγγελία αν η κατάσταση είναι "completed"

Δείτε τον οδηγό Webhooks για λογική επαναπροσπαθειών, βέλτιστες πρακτικές και λεπτομέρειες payload.

Εναλλακτικά: Σύνδεσμοι Πληρωμής

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

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": 2500,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

Η απόκριση περιλαμβάνει ένα payment_url που μπορείτε να μοιραστείτε μέσω email, SMS ή chat. Ο πελάτης μπορεί να προσπαθήσει πληρωμή πολλές φορές (έως 25) μέχρι ο σύνδεσμος να λήξει ή η πληρωμή να επιτύχει.

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

Τι Ακολουθεί;

Ολοκληρώσατε την πρώτη σας πληρωμή. Ορίστε πού να συνεχίσετε:

• Φιλοξενούμενη Σελίδα Πληρωμής — πλήρης αναφορά HPP με όλα τα πεδία αιτήματος και τις επιλογές
• Επαναλαμβανόμενες Πληρωμές — ρύθμιση συνδρομών και προγραμματισμένης χρέωσης
• Πληρωμές με Ένα Κλικ — γρήγορο checkout για επιστρέφοντες πελάτες
• Εξουσιοδότηση / Δέσμευση / Ακύρωση — εξουσιοδοτήστε πρώτα, δεσμεύστε αργότερα (π.χ. κατά την αποστολή)
• Επιστροφές Χρημάτων — επεξεργασία πλήρων και μερικών επιστροφών χρημάτων
• SDKs — επίσημες βιβλιοθήκες για Node.js, Python, PHP, Java/Kotlin, C#/.NET και Ruby
• Πρόσθετα — προκατασκευασμένες ενσωματώσεις για Shopify, WooCommerce, Magento και άλλα

Σχετικά Endpoints

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