API πύλης πληρωμών crypto: τιμολόγια, webhooks, εκταμιεύσεις και white label

Τι κάνει το API μιας πύλης πληρωμών crypto;

Το API κρύβει το blockchain από τον κώδικά σας. Αντί να τρέχετε nodes, να παράγετε διευθύνσεις και να μετράτε επιβεβαιώσεις, καλείτε ένα endpoint για να δημιουργήσετε τιμολόγιο, αποθηκεύετε το αναγνωριστικό της πύλης και περιμένετε ειδοποιήσεις. Η πύλη υπολογίζει την ισοτιμία, παρακολουθεί τα δίκτυα, εφαρμόζει έλεγχο AML και κάνει εκκαθάριση στο υπόλοιπό σας.

Οι περισσότερες πύλες προσφέρουν τα ίδια δομικά στοιχεία με διαφορετικά ονόματα: τιμολόγια ή παραγγελίες για εισερχόμενες πληρωμές, IPN ή callbacks για ειδοποιήσεις, endpoints μετατροπής και υπολοίπου, και payouts ή αναλήψεις για εξερχόμενες μεταφορές. Sandbox υπάρχουν στους περισσότερους παρόχους, για παράδειγμα ξεχωριστός host sandbox στην CoinGate και λογαριασμός sandbox στην NOWPayments, και πρέπει να χρησιμοποιούνται πριν από κάθε δοκιμή στο mainnet.

• API τιμολογίων: δημιουργία, ανάγνωση και ακύρωση αιτημάτων πληρωμής με τιμή σε fiat, αποδεκτά νομίσματα, αναφορά παραγγελίας και URL callback
• Ειδοποιήσεις: webhooks ή IPN σε κάθε αλλαγή κατάστασης, συνήθως υπογεγραμμένα
• API payouts: αποστολή crypto ή fiat σε πελάτες, συνεργάτες ή στο δικό σας πορτοφόλι
• Ισοτιμίες και νομίσματα: λίστα υποστηριζόμενων νομισμάτων, δικτύων, ελάχιστων ποσών και ζωντανές τιμές
• Plugins και SDK: έτοιμες μονάδες για πλατφόρμες ηλεκτρονικού εμπορίου πάνω στο ίδιο API

Πώς λειτουργεί ο κύκλος ζωής του τιμολογίου;

Κάθε πύλη έχει δικό της μοντέλο καταστάσεων, γι' αυτό αντιστοιχίστε τες σε ένα μικρό εσωτερικό σύνολο πριν γράψετε επιχειρηματική λογική. Μόνο μια τελική κατάσταση πληρωμής πρέπει να απελευθερώνει τα αγαθά· οι ενδιάμεσες καταστάσεις υπάρχουν επειδή μια συναλλαγή μπορεί να φανεί στο blockchain πολύ πριν είναι ασφαλές να γίνει αποδεκτή.

Ο πίνακας αντιστοιχίζει δύο δημοσιευμένα μοντέλα καταστάσεων στις καταστάσεις που χρειάζονται οι περισσότερες πλατφόρμες. Η CoinGate, για παράδειγμα, λήγει ένα απλήρωτο τιμολόγιο μετά από 20 λεπτά αφότου ο πελάτης επιλέξει νόμισμα και σημειώνει ως άκυρες τις πληρωμές που επισημαίνουν οι έλεγχοι AML.

Πώς επαληθεύονται τα webhooks και τα IPN crypto;

Αντιμετωπίστε κάθε ειδοποίηση ως μη αξιόπιστη μέχρι να επαληθευτεί. Οι πύλες χρησιμοποιούν διαφορετικά σχήματα: η NOWPayments υπογράφει το ταξινομημένο σώμα JSON με HMAC-SHA512 και το στέλνει στην κεφαλίδα x-nowpayments-sig, η CoinGate στέλνει ένα token που ορίζετε στην παραγγελία και η BitPay συνιστά να ανακτάτε το τιμολόγιο από το API μετά από κάθε ειδοποίηση αντί να εμπιστεύεστε το σώμα της.

Το ασφαλέστερο μοτίβο συνδυάζει και τα δύο: επαληθεύστε την υπογραφή, μετά διαβάστε το τιμολόγιο από το API και ενεργήστε με βάση αυτή την απάντηση. Κοστίζει ένα αίτημα ανά αλλαγή κατάστασης και σας προστατεύει από πλαστά ή επαναληπτικά callbacks.

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

Πώς αντιμετωπίζονται οι ανεπαρκείς, οι υπερβολικές και οι εκπρόθεσμες πληρωμές;

Τα πορτοφόλια και τα ανταλλακτήρια αφαιρούν τέλη ανάληψης και οι πελάτες αντιγράφουν τα ποσά ανακριβώς, επομένως δεν μπορεί να θεωρηθεί δεδομένη η ακριβής πληρωμή. Ορίστε ανοχή και κανόνα για κάθε περίπτωση πριν από την έναρξη και εμφανίστε το αποτέλεσμα στο προσωπικό υποστήριξης.

Πώς λειτουργούν το idempotency και η συμφωνία;

Δημιουργείτε τιμολόγια με τη δική σας αναφορά παραγγελίας και κάντε την κλήση ασφαλή για επανάληψη: αν το αίτημα λήξει, αναζητήστε το τιμολόγιο με την αναφορά πριν δημιουργήσετε άλλο ή χρησιμοποιήστε κλειδί idempotency όπου η πύλη το υποστηρίζει. Ο ίδιος κανόνας ισχύει για τα payouts, όπου ένα διπλό αίτημα στέλνει πραγματικά χρήματα δύο φορές.

Για τη συμφωνία, αποθηκεύετε το αναγνωριστικό τιμολογίου της πύλης, το hash της συναλλαγής, το ποσό σε fiat, το ποσό σε crypto, την ισοτιμία και την προμήθεια. Οι αναφορές εκκαθάρισης παραθέτουν τα payouts ως δέσμες, οπότε η αντιστοίχιση γίνεται από την παραγγελία στο τιμολόγιο και στο payout, όχι από την παραγγελία στη γραμμή της τράπεζας.

Τι χρειάζεται ένα API payouts υπό τον Travel Rule;

Τα endpoints payouts στέλνουν crypto από το υπόλοιπο της πύλης σε μια διεύθυνση, συχνά σε δέσμες για προμήθειες συνεργατών, πωλητές marketplace ή αναλήψεις πελατών. Οι περισσότερες απαιτούν λίστα επιτρεπόμενων διευθύνσεων, έγκριση δύο παραγόντων ή κλειδί API με ξεχωριστά δικαιώματα για payouts.

Στην ΕΕ, ο κανονισμός (ΕΕ) 2023/1113 υποχρεώνει την πύλη να διαβιβάζει πληροφορίες για τον εντολέα και τον δικαιούχο με κάθε μεταφορά και να επαληθεύει την κυριότητα πορτοφολιών self-hosted πάνω από 1.000 EUR. Να περιμένετε τα αιτήματα payout να περιλαμβάνουν όνομα δικαιούχου και τύπο διεύθυνσης και να σχεδιάσετε για μεταφορές που περιμένουν αυτά τα στοιχεία.

Ποιες είναι οι επιλογές πύλης πληρωμών crypto white label;

Οι πλατφόρμες που μεταπωλούν πληρωμές στους δικούς τους εμπόρους θέλουν συχνά τη σελίδα πληρωμής με το δικό τους brand. Υπάρχουν τρία επίπεδα και η τιμή αυξάνεται με τον έλεγχο. Η Plisio, για παράδειγμα, αναφέρει 0,5% για το API και 1,5% για white label, ενώ η NOWPayments πουλά ξεχωριστό προϊόν white label.

Το πλήρες white label μεταφέρει και την ευθύνη, όχι μόνο το brand. Αν κάνετε onboarding εμπόρων και κρατάτε τα υπόλοιπά τους, μπορεί να χρειάζεστε δική σας άδεια MiCA· η χρήση του μοντέλου υπο-εμπόρου μιας πύλης με άδεια κρατά αυτή την υποχρέωση στην πύλη.

Πώς συνδέετε API πυλών crypto μέσω του OrsunPay;

Το OrsunPay ομογενοποιεί τις καταστάσεις, τα webhooks και τις επιστροφές των πυλών crypto σε ένα API, δίπλα στους παρόχους καρτών και τραπεζικών πληρωμών σας, με τους δικούς σας λογαριασμούς πυλών. Δεν φυλάσσει crypto και δεν εκτελεί payouts από δικό του υπόλοιπο· δρομολογεί τα αιτήματα στην πύλη που επιλέγετε και επιστρέφει υπογεγραμμένα γεγονότα χωρίς διπλότυπα.

Πώς να ενσωματώσετε το API μιας πύλης πληρωμών κρυπτονομισμάτων

1. Ανοίξτε λογαριασμούς sandbox Δημιουργήστε λογαριασμούς sandbox και παραγωγής στην πύλη, δημιουργήστε ξεχωριστά κλειδιά API για τιμολόγια και payouts και ορίστε το μυστικό IPN.
2. Αντιστοιχίστε τις καταστάσεις Μεταφράστε τις καταστάσεις της πύλης στις εσωτερικές σας καταστάσεις και αποφασίστε ποια απελευθερώνει τα αγαθά.
3. Δημιουργήστε τιμολόγια με idempotency Στείλτε ποσό σε fiat, νόμισμα, αναφορά παραγγελίας και URL callback· αναζητήστε με την αναφορά πριν επαναλάβετε μια κλήση που έληξε.
4. Επαληθεύστε τις ειδοποιήσεις Ελέγξτε την υπογραφή, ανακτήστε ξανά το τιμολόγιο από το API και επεξεργαστείτε το γεγονός μία φορά.
5. Χειριστείτε τις οριακές περιπτώσεις Υλοποιήστε ροές ανοχής, συμπλήρωσης, επιστροφής και λήξης και δοκιμάστε καθεμία στο sandbox.
6. Συμφωνήστε τις εκκαθαρίσεις Αποθηκεύετε hash συναλλαγής, ισοτιμία και προμήθεια ανά τιμολόγιο και αντιστοιχίζετε καθημερινά τις δέσμες payouts με τις παραγγελίες.