Πώς λειτουργούν οι πληρωμές API για τους παρόχους υπηρεσιών

Η API πληρωμής είναι ένα συμβόλαιο μεταξύ της αίτησής σας και του παρόχου που μετατρέπει «δημιουργία πληρωμής», «επιβεβαίωση» 3DS, «επιστροφή κεφαλαίων», «πληρωμή του πελάτη» και «λήψη κατάστασης» σε αξιόπιστες, επαναλαμβανόμενες κλήσεις. Κάτω από την κουκούλα υπάρχουν δεκάδες κανόνες: μαρκινοποίηση, ιδεατότητα, webhooks, καταπολέμηση της απάτης, ουρές, SLA και έλεγχος. Ακολουθεί ένας πρακτικός χάρτης του τρόπου με τον οποίο λειτουργεί αυτό για τους περισσότερους παρόχους.

Βασικό υπόδειγμα: ποιες οντότητες είναι σχεδόν πάντα

Πληρωμή/χρέωση - απόπειρα διαγραφής (έγκριση + δέσμευση ή άμεση αγορά).

Μέθοδος πληρωμής - κάρτα (PAN/μάρκα), τραπεζικός λογαριασμός/ψευδώνυμο, πορτοφόλι, τοπική μέθοδος.

Πελάτης - οντότητα πελάτη/πληρωτή (μερικές φορές προαιρετική).

Πληρωμή/Μεταφορά - εξερχόμενη πληρωμή στον πελάτη/έμπορο.

Επιστροφή/αναστροφή - επιστροφή στην αρχική πληρωμή (κλειστός βρόχος).

Webhook Event - κοινοποίηση ασύγχρονης κατάστασης.

Διαφορά/Χρέωση - διαφορά σχετικά με το δίκτυο πληρωμών (για κάρτες).

Παραγγελία/τιμολόγιο - επιχειρηματικό πλαίσιο γύρω από την πληρωμή.

Επαλήθευση ταυτότητας και ασφάλεια

Πλήκτρα API/OAuth 2. - για server-to-server.

Οι μάρκες πελατών είναι μάρκες μιας χρήσης για το frontend (ώστε να μην λάμπουν μυστικά).

Μαρκαρισμός καρτών - Το PAN πηγαίνει στον πάροχο. αποθηκεύετε μόνο το σύμβολο.

PCI DSS - εάν δείτε ένα PAN, είστε στη ζώνη PCI; είναι καλύτερο να αποφεύγονται και να χρησιμοποιούνται τα φιλοξενούμενα πεδία/SDK.

HMAC υπογραφή webhooks - έλεγχος ότι το γεγονός προήλθε από τον πάροχο.

Αρχιτεκτονική διπλής ζώνης - δημόσιο μέτωπο (JS/SDK) και ιδιωτική υποστήριξη (κλειδιά, λογική κινδύνου).

Ιδιαιτερότητα, ουρές αναμονής και συνέπεια

Το Idempotency-Key στην κεφαλίδα: η επανάληψη του αιτήματος (με το timeout) δεν δημιουργεί ένα αντίγραφο.

Outbox/Saga μαζί σας: «να στείλετε μια πληρωμή → να γράψετε στο βιβλίο → να περιμένετε το webhook».

Retrai με backoff - μόνο για προσωρινά σφάλματα. Απαιτείται ο ανασυρόμενος/μη ανασυρόμενος πίνακας.

Τυπικά τελικά σημεία (σχήματα και ροή)

1) Κάρτες (Visa/Mastercard κ.λπ.)

POST/πληρωμές - δημιουργία πληρωμής («ποσό», «νόμισμα», «payment _ method _ token», «capture» = ψευδές/αληθές).

POST/πληρωμές/{ id }/επιβεβαίωση - шаг 3-D Secure 2 (πρόκληση/αποτέλεσμα ανακατευθύνσεως).

POST/πληρωμές/{ id }/δέσμευση - σύλληψη μετά την έγκριση (μερική/πλήρης).

POST/πληρωμές/{ id }/επιστροφή - απόδοση (σε μέρη, μέχρι το αρχικό ποσό).

GET/πληρωμές/{ id} - статус (εγκεκριμένα, συλληφθέντα, αποτυχημένα, requires_action).

3-D Secure/SCA: ο πάροχος θα επιστρέψει 'requires _ action' + 'client _ secre /URL για πρόκληση. Μετά την επιβεβαίωση από τον πελάτη, το μπροστινό μέρος θα επιστρέψει το αποτέλεσμα στο backend σας → τραβήξετε '/επιβεβαιώσετε '.

2) A2A/Open Banking (Pay by Bank)

POST/πληρωμές → απάντηση από την «ανακατευθύνουσα _ url» στην τράπεζα του πελάτη.

Ο πελάτης είναι εξουσιοδοτημένος από την τράπεζα → webhook 'payment. πέτυχε/απέτυχε ".

GET/πληρωμές/{ id} - τελική κατάσταση (συχνά μόνο ασύγχρονη).

3) Τοπικές μέθοδοι (PIX, PayID, FPX, iDEAL κ.λπ.)

POST/πληρωμές → να πάρετε 'qr _ code '/' deeplink '/' copy _ code'.

Εμφάνιση του χρήστη, αναμονή για το webhook σχετικά με την εγγραφή.

Τα χρονοδιαγράμματα κωδικών και τα TTL αποτελούν μέρος της σύμβασης.

4) Πληρωμές

POST/πληρωμές («ποσό», «νόμισμα», «προορισμός _ token» или «card _ token »/« bank _ alias»).

GET/πληρωμές/{ id} - статусы ('queed', 'sent', 'paid', 'failed').

Πληρωμή Webhooks. αμειβόμενη/αποτυχημένη "είναι η πηγή της αλήθειας.

Κλειστός βρόχος: είναι προτιμότερο να πληρώνεται στην πηγή (αντιστροφή) πριν από εναλλακτικές λύσεις.

Webhooks: «η πηγή της αλήθειας»

Γεγονότα: "πληρωμή. εν αναμονή/έγκριση/δέσμευση/αποτυχία πληρωμής «,». , "επιστροφή χρημάτων. διαδέχθηκε «,» πληρωμή. αμειβόμενη διαφορά «,». δημιουργήθηκε ', κλπ.

Παράδοση: με τα retrays υπογεγραμμένα από την HMAC, συχνά «τουλάχιστον μία φορά» → κρατούν τον χειριστή idempotent.

Βέλτιστη πρακτική: επεξεργασία του webhook → ενημέρωση του βιβλίου → απόκριση 2xx. Κάθε επιχειρηματική λογική μετά είναι ασύγχρονη.

Σφάλμα και επεξεργασία κατάστασης

Κωδικοί HTTP: '2xx' επιτυχία; σφάλμα πελάτη '4xx' (επικύρωση, απάτη/χρεοκοπία τράπεζας, εσφαλμένη ένδειξη), '5xx' - πάροχος.

: 'ανεπαρκής _ κεφάλαια', 'do _ not _ honor', 'κλεμμένη _ κάρτα', 'όριο _ υπέρβαση', 'κίνδυνος _ παρακμή', 'τράπεζα _ μη διαθέσιμη'.

Redo παράθυρα: για 3DS - δεν μπορείτε να αποσύρετε ατελείωτα? για το A2A - ισχύουν οι ανακατευθύνσεις/κωδικοί TTL· για πληρωμές - backoff.

Καταπολέμηση της απάτης και του κινδύνου

Δακτυλικά αποτυπώματα συσκευής και δεδομένα συμπεριφοράς - μέσω του JS/SDK του παρόχου ή του δικού σας στρώματος.

Κατάλογοι: κίνδυνος BIN, μαύρος/λευκός κατάλογος μεθόδων/ASN/χώρες.

Ρυθμιζόμενες πύλες: όρια σε νέα εργαλεία, ψύξη, ταχύτητα, έλεγχος κατωφλίου RG/AML.

Πολιτικές: 'pass/step-up/hold/block' βάσει κανόνων βαθμολόγησης +.

Χαρακτηριστικά σε σιδηροτροχιές

Κάρτες: εξουσιοδότηση έναντι εκκαθάρισης (το ποσό μπορεί να μετατοπιστεί), 3DS2, αποδόσεις στην αρχική συναλλαγή, διαφορές/χρεώσεις.

Τραπεζική: ανακατευθύνει/συγκατάθεση ροή, υψηλό apruv, χαμηλό κόστος? όλα είναι ασύγχρονα και εξαρτώνται σε μεγάλο βαθμό από την τράπεζα.

Τοπική νηστεία: QR/ψευδώνυμο, στιγμιαίο webhook, TTL και αυστηρή συλλογή.

OCT/Push-to-Card (πληρωμές με κάρτα): χρειάζεστε μάρκες καρτών, υποστήριξη Fast Funds από τον εκδότη, χωρίς 3DS.

Έκδοση και συμβατότητα

Εκδόσεις API: '/v1 ', «εκδόσεις δεδομένων» στην επικεφαλίδα ή τις phicheflags.

Αλλαγές συμβατές προς τα πίσω: μόνο μη καταστρεπτικά πεδία.

Απαξιώσεις: χρονοδιάγραμμα για την απόσυρση παλαιών εκδόσεων, οδηγούς μετανάστευσης, διπλά webhooks κατά τη διάρκεια της μετάβασης.

Παρατηρησιμότητα και SLA

Μετρήσεις: p95 εξουσιοδότηση/χρόνος πληρωμής, επιτόκιο έγκρισης BIN/τράπεζα/μέθοδος, μερίδιο των retrays, webhooks-lag.

Αρχεία καταγραφής: συσχέτιση με 'request _ i ,' idempotency _ key ',' payment _ id '.

Ειδοποιήσεις: αύξηση των αρνήσεων για συγκεκριμένη τράπεζα/χώρα, αύξηση των χρονοδιαγραμμάτων, διπλά γεγονότα.

Σάρωση και χρηματοδότηση

Γραμματόσημο: διπλή εγγραφή, αμετάβλητα αρχεία καταγραφής, κατάσταση «εγκεκριμένου/δεσμευμένου/επιστρεφόμενου».

Τριπλή συλλογή: το βιβλίο σας ↔ webhooks ↔ provider/bank reports.

Παραπομπές: διατήρηση «πάροχος _ αναφοράς», «δίκτυο _ αναφορά», «payout _ reference» - αυτό εξοικονομεί τη στήριξη.

Αμμοκιβώτιο, πιστοποίηση και παραγωγή

Sandbox: δοκιμαστικές μάρκες/κάρτες/τράπεζες, προσομοίωση 3DS/redirects, «κουμπιά» για καταστάσεις webhook.

Περιπτώσεις δοκιμής: επιτυχία/αποτυχία, πρόκληση 3DS, χρονοδιάγραμμα παρόχου, αντίγραφο webhook, μερική σύλληψη/επιστροφή χρημάτων, επαναπροσανατολισμός ακύρωσης, αποτυχία πληρωμής.

Go-live: prod πλήκτρα, webhook domains, IP-ablist, δυνατότητα καταπολέμησης της απάτης, καθορισμός ορίων και συναγερμών.

Μίνι παραδείγματα (σχηματικά)

Δημιουργία πληρωμής (κάρτα)


POST/v1/πληρωμές
{
"ποσό": 9232, "νόμισμα": "EUR", "payment_method_token": "pm_tok_123," "δέσμευση": αλήθεια, "μεταδεδομένα": {"order _ id": "ORD-1001"}
}
200 {"i :"  "" status ":"  " : {" type ":" redirec , "ur :"... "}}

Webhook για την επιτυχή εγγραφή


POST/webhooks
{
"τύπος": "πληρωμή. capted «,» data «: {» id «:» pay _ ab , «ποσό»: 9232, «νόμισμα»: «EUR», «μεταδεδομένα»: {«order _ id»: «ORD-1001»}
}

Πληρωμή


POST/v1/πληρωμές
{
"ποσό": 5000, "νόμισμα": "EUR", "destination_token": "dest_tok_456," "μεταδεδομένα": {"χρήστης _ id":" u _ 77"}
}

Κατάλογος ελέγχου εφαρμογής

1. Βασική αρχιτεκτονική: μυστικά διακομιστή ξεχωριστά, μυστικά πελατών - εφάπαξ.

2. Idempotency: σε κάθε εγγραφή call + idempotent webhook handlers.

3. Webhooks: υπογραφή HMAC, ρετράι, ουρά εργασίας, παρακολούθηση καθυστέρησης.

4. και ανακατευθύνει: χειρισμός ακυρώσεων/timeouts, δοκιμάζοντας φίλο-UX και πάλι.

5. Antifraud/όρια: ταχύτητα, νέες λεπτομέρειες, μαύρες λίστες, όρια RG/AML.

6. Ledger και συμφιλίωση: διπλή είσοδος, τριπλή συμφιλίωση, καταχωρίσεις ανωμαλίας.

7. Ενορχήστρωση: εφεδρικός πάροχος, κανόνες δρομολόγησης από τον BIN/χώρα/ποσό.

8. Παρακολούθηση: τα ταμπλό εγκρίνουν το επιτόκιο/p95/retrays, προειδοποιήσεις από τράπεζες/μεθόδους.

9. Νομικό/PCI: συμβολοσειρά, πολιτική επιστροφών, κλειστός βρόχος πληρωμής.

10. Σχέδιο αποικοδόμησης: κανάλι θανατηφόρου διακόπτη, ουρές αναμονής, χειροκίνητη λειτουργία για κρίσιμες λειτουργίες.

Συχνά σφάλματα

Αποθήκευση PAN στο πλευρό του χωρίς PCI και μαρκινοποίηση.

Καμία ταυτότητα → διπλή πληρωμή/πληρωμή με χρονοδιαγράμματα.

Η λογική για τις σύγχρονες απαντήσεις χωρίς να λαμβάνονται υπόψη τα webhooks.

Ένας πάροχος στην αγορά, χωρίς οπισθοδρόμηση/καταρράκτες.

No 3DS undo/redirect processing → lost recycle cins.

Μια αδύναμη δέσμη → «παγωμένες» και «χαμένες» συναλλαγές.

Η έλλειψη σαφών SLA και προειδοποιήσεων → το πρόβλημα που βλέπει ο πελάτης, όχι εσείς.

Mini-FAQ

Ποιο είναι πιο αξιόπιστο: συγχρονισμένη κατάσταση ή webhook

Webhook είναι η πηγή της αλήθειας? συγχρονισμένη απόκριση - μόνο «δράση αποδεκτή/αναγκαία».

Μπορείτε να το κάνετε χωρίς 3DS

Εξαρτάται από τη ρύθμιση/τον κίνδυνο. στην ΕΚ/ΗΒ - η SCA είναι υποχρεωτική· για υψηλού κινδύνου, η επιτάχυνση είναι καλύτερη.

Πώς θα αυξηθεί το ποσοστό έγκρισης

BIN/τράπεζα/μέθοδος ενορχήστρωσης, τοπικές σιδηροτροχιές, έξυπνες ρετρά, σωστοί περιγραφικοί δείκτες, χαμηλή απάτη FPR.

Γιατί η πληρωμή είναι «όχι άμεση»

Εξαρτάται από τον σιδηρόδρομο (OST/A2A/τοπικό), την τράπεζα και τα όρια του αποδέκτη. Ας έχουμε ένα τίμιο παράθυρο SLA και status stream.

Οι πληρωμές API δεν είναι μόνο "δημιουργούν μια πληρωμή. "Η πειθαρχία αυτή: ασφαλής εξακρίβωση ταυτότητας → μαρκαρίσματος → ιδιαιτερότητας → ασύγχρονων δικτυακών βιβλίων → βιβλίων και αναδίπλωσης → καταπολέμησης της απάτης/AML → ενορχήστρωση και παρακολούθηση. Κατασκευάστε τη διαδικασία σύμφωνα με αυτό το σύστημα, διατηρήστε εφεδρικούς διαύλους και διαφανή UX - και το επίπεδο πληρωμών σας θα είναι γρήγορο, προβλέψιμο και ανθεκτικό στις αποτυχίες των τραπεζών και των παρόχων.