Developers
Τρεις κλήσεις και ένα webhook.
Το Gateway είναι hosted checkout, γι' αυτό η ενσωμάτωση είναι σκόπιμα μικρή: δημιουργείτε μια παραγγελία, στέλνετε τον πελάτη στη σελίδα, επαληθεύετε το υπογεγραμμένο αποτέλεσμα. Όσα βλέπετε παρακάτω είναι ολόκληρη η επιφάνεια — το UI πληρωμής, η λογική των μεθόδων, το 3-D Secure, τα wallets και οι αποδείξεις είναι δική μας δουλειά, να τα χτίζουμε και να τα κρατάμε ενημερωμένα.
Η δομή
Με τι ενσωματώνεστε.
- REST πάνω από HTTPS
- JSON μέσα, JSON έξω
- Bearer API keys
- Idempotency keys
- Υπογεγραμμένα webhooks
- Προστασία από replay
- Λειτουργίες test και live
- SDK για iOS & Android
- Plugins για e-shop
- Embedded πεδία
Quickstart
Από το μηδέν σε πληρωμένη παραγγελία.
Η ιδανική διαδρομή ολόκληρη. Τα ποσά δίνονται σε υποδιαιρέσεις του νομίσματος (λεπτά), οι αναφορές είναι δικές σας και το checkout URL είναι εκεί όπου ανακατευθύνετε τον πελάτη. Το βασικό URL του API δίνεται μαζί με τα κλειδιά sandbox — κάντε export ως PROTOCORE_API_BASE και οι κλήσεις παρακάτω τρέχουν ακριβώς όπως είναι γραμμένες.
Δημιουργήστε την παραγγελία
Μία κλήση με το ποσό, το νόμισμα και τη δική σας αναφορά. Το idempotency key το δημιουργείτε εσείς — ένα αίτημα που επαναλαμβάνεται επιστρέφει την αρχική παραγγελία αντί να δημιουργήσει δεύτερη.
curl -X POST "$PROTOCORE_API_BASE/v1/orders" \
-H "Authorization: Bearer $PROTOCORE_API_KEY" \
-H "Idempotency-Key: 9F21-0716" \
-H "Content-Type: application/json" \
-d '{
"amount": 4900,
"currency": "EUR",
"reference": "9F21-0716",
"line_items": [
{ "name": "Brand identity sprint", "amount": 3850 },
{ "name": "Typeface licensing", "amount": 600 },
{ "name": "Rush delivery", "amount": 400 }
],
"return_url": "https://arcstudio.ro/thanks"
}'Στείλτε τον πελάτη στο checkout
Η απάντηση περιέχει ένα checkout URL στο δικό σας checkout host — αυτό που εκδίδεται με το sandbox ή το δικό σας domain, μόλις το κατευθύνετε σε εμάς. Κάντε redirect ή ανοίξτε το μέσα από το SDK· σε εκείνη τη σελίδα βρίσκονται οι μέθοδοι πληρωμής, τα wallets και το 3-D Secure, οπότε δεν χρειάζεται να χτίσετε τίποτα από τη δική σας πλευρά.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Επαληθεύστε το υπογεγραμμένο αποτέλεσμα
Όταν ολοκληρωθεί η πληρωμή, ένα υπογεγραμμένο event φτάνει στο endpoint σας. Επαληθεύστε την υπογραφή με το webhook secret πριν εμπιστευτείτε οτιδήποτε και μετά προχωρήστε στην εκτέλεση με βάση την αναφορά που ήδη γνωρίζετε.
{
"type": "order.paid",
"id": "evt_7Ka2Lm",
"created": "2026-07-23T09:41:02Z",
"data": {
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"method": "usdc",
"settlement": { "currency": "EUR", "amount": 4900, "rate": "0.9184" }
}
}Αναφορά
Τα endpoints που θα χρησιμοποιήσετε πραγματικά.
Στα docs υπάρχουν περισσότερα, αλλά αυτό είναι το σύνολο από το οποίο οι περισσότερες ενσωματώσεις δεν ξεφεύγουν ποτέ.
Webhooks
Τι ακούει το backend σας.
Κάθε event φέρει την αναφορά παραγγελίας που δημιουργήσατε, οπότε ο handler σας μπορεί να είναι ένα switch στον τύπο και μια αναζήτηση στη δική σας πλευρά.
Ελέγξτε την υπογραφή πριν εμπιστευτείτε το body.
Κάθε παράδοση φέρει timestamp και υπογραφή HMAC πάνω στο ακατέργαστο body. Συγκρίνετε σε σταθερό χρόνο, απορρίψτε ό,τι είναι παλαιότερο από το περιθώριο ανοχής σας και θεωρήστε ένα διπλότυπο event id ως ήδη χειρισμένο — επαναλαμβάνουμε την αποστολή όταν η απάντηση δεν είναι 2xx, άρα και ο handler σας πρέπει να είναι idempotent.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody, header, secret) {
const [ts, sig] = header.split(",").map((p) => p.split("=")[1]);
const expected = createHmac("sha256", secret)
.update(`${ts}.${rawBody}`)
.digest("hex");
const a = Buffer.from(sig, "hex");
const b = Buffer.from(expected, "hex");
if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
// Reject replays outside a five-minute window.
return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}Εγγυήσεις
Οι ιδιότητες πάνω στις οποίες μπορείτε να χτίσετε.
Idempotent δημιουργίες
Κάθε δημιουργία παραγγελίας δέχεται idempotency key. Ένα αίτημα που επαναλαμβάνεται — μετά από timeout, deploy ή επαναποστολή από την ουρά — επιστρέφει την αρχική παραγγελία αντί να χρεώσει δύο φορές.
Υπογεγραμμένα events με προστασία από replay
Τα webhooks φέρουν υπογραφή HMAC με timestamp και σταθερό event id. Οι αποστολές επαναλαμβάνονται με backoff μέχρι το endpoint σας να απαντήσει 2xx, ώστε ένα παράθυρο deploy να μη χάνει πληρωμή.
Μία αναφορά, από άκρη σε άκρη
Η αναφορά που δίνετε κατά τη δημιουργία εμφανίζεται στο checkout, στην απόδειξη, στο webhook, στο payout και σε κάθε μεταγενέστερη επιστροφή χρημάτων. Δεν υπάρχει δεύτερο αναγνωριστικό να αντιστοιχίζετε ανάμεσα σε συστήματα.
Το test mode τρέχει τον ίδιο κώδικα
Τα test keys τρέχουν τις ίδιες ακριβώς ροές σε test sessions. Ό,τι περνά στο test είναι αυτό που βγαίνει στην παραγωγή — η διαφορά είναι ποια κλειδιά στέλνετε, όχι ποια endpoints καλείτε.
Δεδομένα δοκιμών
Πώς να δοκιμάσετε τις διαδρομές που μετράνε.
Πίσω από κάθε διαδρομή παρακάτω υπάρχει μια δοκιμαστική κάρτα, που θα βρείτε μαζί με τα κλειδιά σας όταν εκδοθεί το sandbox. Οι αριθμοί είναι ανά sandbox και δεν δημοσιεύονται εδώ, ώστε να παραμένουν σωστοί όσο αλλάζουν τα δοκιμαστικά εύρη των card schemes. Η συμπεριφορά είναι σε κάθε περίπτωση ντετερμινιστική: ένα τεστ ελέγχει μια απόρριψη το ίδιο εύκολα με μια επιτυχία.
Πάρτε κλειδιά και ξεκινήστε.
Ένας merchant στο sandbox με κλειδιά API, webhook secrets και όλες τις μεθόδους ενεργές — μαζί με την πλήρη τεκμηρίωση, ώστε η ομάδα σας να ενσωματώσει πριν υπογραφεί οτιδήποτε.