Πληρωμές Fast Track

Ο πληρωτής ανοίγει αυτή τη διεύθυνση URL και εγκρίνει την πληρωμή στην τράπεζά του. Στο παρασκήνιο δημιουργείται η ίδια αμετάβλητη πρόθεση πληρωμής όπως στο υπόλοιπο API: το ποσό, ο δικαιούχος και η αιτιολογία καθορίζονται πριν φτάσουν στο πρόγραμμα περιήγησης και η κεφαλίδα Idempotency-Key αποτρέπει δεύτερη χρέωση αν η κλήση διακοπεί.

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

POST /payments/?action=fast-track

Υποχρεωτικές κεφαλίδες: Content-Type: application/json, X-API-Key και Idempotency-Key. Το κλειδί έχει από 16 έως 128 χαρακτήρες, ξεκινά με γράμμα ή αριθμό και δέχεται μόνο γράμματα, αριθμούς και . _ : -· ένα UUID v4 είναι αποδεκτό. Αν λείπει ή το μήκος του δεν είναι έγκυρο, η απάντηση είναι 400 idempotency_key_required· αν χρησιμοποιεί άλλους χαρακτήρες, 422 invalid_customer_reference. Αυτό το κλειδί είναι επίσης η αναφορά του εμπόρου: δεν χρειάζεται να το στείλετε στο σώμα. Αν επαναλάβετε το ίδιο κλειδί με το ίδιο σώμα, λαμβάνετε ξανά την ίδια διεύθυνση URL. Αν το επαναχρησιμοποιήσετε με άλλα δεδομένα, η απάντηση είναι 409 idempotency_conflict.

Όλα τα πεδία είναι υποχρεωτικά εκτός από το logo. Το σώμα ακολουθεί λίστα επιτρεπόμενων πεδίων. Ένα επιπλέον πεδίο, ή ένα υποχρεωτικό που λείπει, επιστρέφει 422 invalid_request. Το logo αποτελεί μέρος της πληρωμής: η επανάληψη του ίδιου Idempotency-Key με άλλο logo επιστρέφει επίσης 409 idempotency_conflict.

Μια άμεση μεταφορά δεν έχει δικό της ανώτατο όριο σε αυτό το API. Η τράπεζα απορρίπτει όποια δεν μπορεί να αποδεχθεί, και λόγω ποσού, και αυτή η απόρριψη φτάνει ως KO στο notification_url.

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"
: "${WR_PAYMENT_IDEMPOTENCY_KEY:?Genere un UUID v4 para este pago}"

curl --request POST 'https://api.wealthreader.com/payments/?action=fast-track' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "amount": "15.50",
    "currency": "EUR",
    "beneficiary": {
      "name": "Comercio Online S.L.",
      "iban": "ES9121000418450200051332"
    },
    "reference": "Pedido 78901",
    "priority": "normal",
    "notification_url": "https://tienda.example.com/pagos/aviso",
    "logo": "https://tienda.example.com/marca/logo.svg"
  }'

Η απάντηση, με 201 την πρώτη φορά και 200 αν το κλειδί υπήρχε ήδη, περιέχει τη διεύθυνση URL και το αναγνωριστικό της πληρωμής:

{
  "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…&api_origin=https%3A%2F%2Fapi.wealthreader.com",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

Ανακατευθύνετε τον πληρωτή στη διεύθυνση URL. Το token βρίσκεται στο fragment, λήγει μαζί με το widget (συνήθως σε 15 λεπτά) και δεν πρέπει να καταγράφεται στα αρχεία καταγραφής σας. Αποθηκεύστε το payment_intent_id μαζί με την παραγγελία σας.

Ειδοποίηση OK ή KO

Όταν η Wealthreader ελέγχει την κατάσταση της πληρωμής και τη βρίσκει σε τελική κατάσταση, εκτελεί POST στο notification_url με Content-Type: application/json και User-Agent: WealthReader-Payments:

{
  "outcome": "ok",
  "payment_status": "settled",
  "customer_reference": "11111111-1111-4111-8111-111111111111",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

• Το outcome είναι ok μόνο αν η τράπεζα έχει διακανονίσει την πληρωμή (settled). Τα rejected, cancelled, expired και failed ειδοποιούν ko. Ένα αμφίσημο αποτέλεσμα (reconciliation_required) δεν είναι τελικό και δεν ειδοποιείται.
• Το customer_reference είναι το δικό σας Idempotency-Key και το payment_intent_id είναι το αναγνωριστικό που επιστράφηκε κατά τη δημιουργία της πληρωμής.
• Απαντήστε με 2xx ώστε η ειδοποίηση να θεωρηθεί παραδομένη. Η Wealthreader περιμένει το πολύ 3 δευτερόλεπτα και δεν ακολουθεί ανακατευθύνσεις.
• Η ίδια ειδοποίηση μπορεί να φτάσει περισσότερες από μία φορές: χειριστείτε τον συνδυασμό customer_reference και outcome ως idempotent.
• Μια διεύθυνση URL που δεν είναι δημόσια https απορρίπτεται κατά τη δημιουργία της πληρωμής και ελέγχεται ξανά πριν από κάθε αποστολή.

Πότε φτάνει. Η κατάσταση ελέγχεται όσο ο πληρωτής παραμένει στη σελίδα πληρωμής, η οποία την ερωτά έως το τελικό αποτέλεσμα ή έως ότου λήξει η συνεδρία πληρωμής, καθώς και κάθε φορά που ερωτάτε το POST /payments/?action=status. Δεν υπάρχει ξεχωριστή προγραμματισμένη αποστολή: αν ο πληρωτής κλείσει τη σελίδα πριν ολοκληρώσει η τράπεζα, ή αν ο διακομιστής σας δεν απαντήσει με 2xx, η ειδοποίηση αποστέλλεται στον επόμενο έλεγχο. Γι' αυτό, αν δεν έχετε λάβει την ειδοποίηση λίγα λεπτά μετά την ανακατεύθυνση του πληρωτή, ελέγξτε την κατάσταση με το payment_intent_id· αυτό το ερώτημα ενεργοποιεί επίσης την εκκρεμή ειδοποίηση. Δείτε Καταστάσεις, περιοδικός έλεγχος και συμφωνία πληρωμών.

Η ειδοποίηση δεν είναι υπογεγραμμένη. Πριν παραδώσετε ένα αγαθό ή μια υπηρεσία αξίας, επιβεβαιώστε το αποτέλεσμα με POST /payments/?action=status χρησιμοποιώντας το X-API-Key σας και το payment_intent_id: μόνο το payment_status: settled σε αυτή την απάντηση αποτελεί οικονομική επιβεβαίωση.