Φιλοξενούμενη Σελίδα Πληρωμής (HPP)

Αποδεχτείτε πληρωμές χρησιμοποιώντας τη φιλοξενούμενη σελίδα πληρωμής της Cost+

Η Φιλοξενούμενη Σελίδα Πληρωμής (HPP) είναι η φόρμα πληρωμής συμβατή με PCI DSS της Cost+. Σας επιτρέπει να δέχεστε πληρωμές χωρίς να χειρίζεστε ευαίσθητα δεδομένα κάρτας στους δικούς σας διακομιστές. Δημιουργείτε μια παραγγελία μέσω του API, ανακατευθύνετε τον πελάτη στη φιλοξενούμενη σελίδα, και αυτός επιστρέφει στον ιστότοπό σας μετά την πληρωμή.

Πώς Λειτουργεί

Ο διακομιστής σας δημιουργεί μια παραγγελία καλώντας POST /v1/orders/.
Το API επιστρέφει ένα URL που οδηγεί στη φιλοξενούμενη σελίδα πληρωμής.
Ανακατευθύνετε τον πελάτη στη σελίδα πληρωμής.
Ο πελάτης ολοκληρώνει την πληρωμή στη φιλοξενούμενη σελίδα της Cost+.
Ο πελάτης ανακατευθύνεται πίσω στο return_url σας (ή στο failure_url για αποτυχημένες πληρωμές).
Η Cost+ στέλνει μια ειδοποίηση webhook στο webhook_url σας με την κατάσταση παραγγελίας.

Η φιλοξενούμενη σελίδα πληρωμής είναι πλήρως συμβατή με PCI DSS. Δεν χρειάζεται ποτέ να χειρίζεστε ακατέργαστους αριθμούς καρτών ή ευαίσθητα δεδομένα πληρωμής στους διακομιστές σας.

Δημιουργία Παραγγελίας

Υπάρχουν δύο προσεγγίσεις για τη χρήση του HPP:

Προσέγγιση 1: Εμφάνιση Όλων των Μεθόδων Πληρωμής (Απλούστερη)

Δημιουργήστε μια παραγγελία χωρίς να καθορίσετε transactions. Η απόκριση περιλαμβάνει ένα order_url — ο πελάτης ανακατευθύνεται εκεί και βλέπει όλες τις μεθόδους πληρωμής που είναι ενεργοποιημένες στον λογαριασμό σας:

Request

{
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-order-id-1",
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook"
}

Response

{
  "id": "43114fde-da30-4115-8004-b7f808f9b25c",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "order_url": "https://pay.costplus.online/43114fde.../select-payment-method/",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook"
}

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

Προσέγγιση 2: Προεπιλογή Μεθόδων Πληρωμής

Δημιουργήστε μια παραγγελία με πίνακα transactions για να ελέγξετε ποιες μέθοδοι πληρωμής εμφανίζονται και με ποια σειρά. Κάθε συναλλαγή περιλαμβάνει ένα payment_method, και η απόκριση επιστρέφει ένα payment_url μέσα στο αντικείμενο συναλλαγής:

Request

{
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-order-id-1",
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    { "payment_method": "credit-card" }
  ]
}

Response

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "new",
      "payment_url": "https://pay.costplus.online/4851e31c.../credit-card/d291f03f.../"
    }
  ]
}

Ανακατευθύνετε τον πελάτη στο payment_url από τη συναλλαγή.

Αν παρέχετε μόνο μία εγγραφή στον πίνακα transactions, ο πελάτης μεταφέρεται απευθείας στη συγκεκριμένη μέθοδο πληρωμής χωρίς να βλέπει οθόνη επιλογής. Ο πίνακας flags περιέχει "is-test" όταν χρησιμοποιείτε κλειδί API sandbox.

Πεδία Αιτήματος

Πεδίο	Απαιτούμενο	Περιγραφή
`currency`	Ναι	Κωδικός νομίσματος ISO 4217 (π.χ., `EUR`, `GBP`, `SEK`)
`amount`	Ναι	Ποσό σε λεπτά. Για παράδειγμα, 12,95 EUR αναπαρίσταται ως `1295`
`merchant_order_id`	Όχι	Το δικό σας αναγνωριστικό αναφοράς για την παραγγελία
`return_url`	Όχι	URL ανακατεύθυνσης του πελάτη μετά την πληρωμή (προεπιλογή για όλες τις καταστάσεις)
`failure_url`	Όχι	URL ανακατεύθυνσης του πελάτη σε κατάσταση `cancelled`, `expired` ή `error` (δείτε URL Επιστροφής παρακάτω)
`locale`	Όχι	Γλώσσα για τη σελίδα πληρωμής. Υποστηριζόμενες: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	Όχι	Περιγραφή της παραγγελίας, εμφανίζεται στον πελάτη
`payment_methods`	Όχι	Filter to a single payment method (e.g. `["credit-card"]`). Omit to show all enabled methods. For multiple specific methods, use the `transactions` array instead
`webhook_url`	Όχι	URL για λήψη ειδοποιήσεων αλλαγής κατάστασης
`expiration_period`	Όχι	Διάρκεια ISO 8601 για λήξη παραγγελίας. Προεπιλογή `PT30M` (30 λεπτά)

Το πεδίο amount είναι πάντα στη μικρότερη μονάδα νομίσματος (λεπτά). Η μετάδοση 1295 σημαίνει 12,95 στο δεδομένο νόμισμα. Η μετάδοση 1295.00 ή 12.95 θα προκαλέσει σφάλμα ή λανθασμένη χρέωση.

Πολλαπλές Μέθοδοι Πληρωμής

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

"transactions": [
  { "payment_method": "credit-card" },
  { "payment_method": "apple-pay" }
]

The payment_methods field on orders accepts at most one value. To offer multiple specific methods, always use the transactions array. If you need a reusable link with multiple payment methods, consider Payment Links instead, which support a true payment_methods array.

URL Επιστροφής

Μετά την πληρωμή, ο πελάτης ανακατευθύνεται βάσει της κατάστασης παραγγελίας και των URL που παρείχατε:

Όταν έχουν οριστεί τόσο return_url όσο και failure_url:
- cancelled, expired ή error → ο πελάτης ανακατευθύνεται στο failure_url
- Όλες οι άλλες καταστάσεις → ο πελάτης ανακατευθύνεται στο return_url
Όταν έχει οριστεί μόνο return_url:
- Όλες οι καταστάσεις → ο πελάτης ανακατευθύνεται στο return_url

Χρησιμοποιήστε το failure_url για να εμφανίσετε μια σελίδα επανάληψης ή υποστήριξης για αποτυχημένες πληρωμές, ενώ το return_url εμφανίζει επιβεβαίωση παραγγελίας. Αν χρειάζεστε μόνο έναν προορισμό, αρκεί μόνο το return_url.

Συμπεριφορά Κουμπιού Ακύρωσης

Η φιλοξενούμενη σελίδα πληρωμής περιλαμβάνει ένα κουμπί ακύρωσης. Όταν ο πελάτης το πατήσει, ανακατευθύνεται στο failure_url (αν παρέχεται) ή στο return_url. Η κατάσταση παραγγελίας θα μεταβεί σε cancelled. Πάντα επαληθεύετε την κατάσταση παραγγελίας μέσω του API ή webhooks αντί να βασίζεστε μόνο στην ανακατεύθυνση.

Σχετικά Endpoints

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

Φιλοξενούμενη Σελίδα Πληρωμής (HPP)

On this page