Φιλοξενούμενη Σελίδα Πληρωμής (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://api.costplus.online/pay/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://api.costplus.online/pay/4851e31c.../select-payment-method/credit-card/d291f03f.../"
    }
  ]
}

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

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

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

Πεδίο	Απαιτούμενο	Περιγραφή
`currency`	Ναι	Κωδικός νομίσματος ISO 4217 (π.χ., `EUR`, `GBP`, `SEK`)
`amount`	Ναί	Ποσό στη δευτερεύουσα μονάδα ISO 4217 του νομίσματος. Για παράδειγμα, το 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`	Οχι	Φιλτράρισμα σε έναν μεμονωμένο τρόπο πληρωμής (π.χ. `["credit-card"]`). Παράλειψη εμφάνισης όλων των ενεργοποιημένων μεθόδων. Για πολλές συγκεκριμένες μεθόδους, χρησιμοποιήστε τον πίνακα `transactions`
`webhook_url`	Όχι	URL για λήψη ειδοποιήσεων αλλαγής κατάστασης
`expiration_period`	Όχι	Διάρκεια ISO 8601 για λήξη παραγγελίας. Προεπιλογή `PT30M` (30 λεπτά)

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

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

Υπάρχουν δύο τρόποι για να ελέγξετε ποιοι τρόποι πληρωμής εμφανίζονται στη φιλοξενούμενη σελίδα:

Επιλογή A — payment_methods (μονό φίλτρο). Περάστε έναν πίνακα ενός στοιχείου για να περιορίσετε την παραγγελία σε έναν τρόπο πληρωμής. Παραλείψτε εντελώς το πεδίο για να εμφανίσετε όλες τις μεθόδους που είναι ενεργοποιημένες για τον λογαριασμό σας.

Επιλογή Β — πίνακας transactions (συνιστάται για πολλαπλές μεθόδους). Προσθέστε μία καταχώριση ανά τρόπο πληρωμής. Κάθε συναλλαγή αποκτά το δικό της payment_url και οι μέθοδοι εμφανίζονται με σειρά πίνακα στη φιλοξενούμενη σελίδα:

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

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

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