Plăți Fast Track

Plătitorul deschide acel URL și autorizează plata în banca sa. În fundal se creează aceeași intenție imuabilă ca în restul API-ului: suma, beneficiarul și descrierea plății sunt fixate înainte de a ajunge în browser, iar antetul Idempotency-Key previne o a doua debitare dacă apelul se întrerupe.

Crearea plății

POST /payments/?action=fast-track

Antete obligatorii: Content-Type: application/json, X-API-Key și Idempotency-Key. Cheia are între 16 și 128 de caractere, începe cu o literă sau o cifră și acceptă doar litere, cifre și . _ : -; un UUID v4 este potrivit. Dacă lipsește sau lungimea ei nu este validă, răspunsul este 400 idempotency_key_required; dacă folosește alte caractere, 422 invalid_customer_reference. Această cheie este și referința comerciantului: nu trebuie trimisă în corp. Dacă repeți aceeași cheie cu același corp, primești din nou același URL. Dacă o reutilizezi cu alte date, răspunsul este 409 idempotency_conflict.

Toate câmpurile sunt obligatorii, cu excepția logo. Corpul respectă o listă de câmpuri permise. Un câmp în plus sau unul obligatoriu care lipsește răspunde cu 422 invalid_request. logo face parte din plată: repetarea aceleiași Idempotency-Key cu alt logo dă tot 409 idempotency_conflict.

Un transfer instant nu are o limită proprie în acest API. Banca respinge transferul pe care nu îl poate accepta, inclusiv din cauza sumei, iar această respingere ajunge ca KO la 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"
  }'

Răspunsul, cu 201 prima dată și 200 dacă cheia exista deja, conține URL-ul și identificatorul plății:

{
  "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"
}

Redirecționează plătitorul către URL. Tokenul se află în fragment, expiră odată cu widgetul (de obicei 15 minute) și nu trebuie înregistrat în logurile tale. Păstrează payment_intent_id împreună cu comanda ta.

Notificarea de OK sau KO

Când Wealthreader verifică starea plății și o găsește într-o stare finală, face un POST către notification_url cu Content-Type: application/json și 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 este ok doar dacă banca a decontat plata (settled). rejected, cancelled, expired și failed generează notificarea ko. Un rezultat ambiguu (reconciliation_required) nu este final și nu se notifică.
• customer_reference este Idempotency-Key a ta, iar payment_intent_id este identificatorul returnat la crearea plății.
• Răspunde cu 2xx pentru ca notificarea să fie considerată livrată. Wealthreader așteaptă cel mult 3 secunde și nu urmează redirecționările.
• Aceeași notificare poate sosi de mai multe ori: tratează combinația customer_reference și outcome ca idempotentă.
• Un URL care nu este https public este respins la crearea plății și este verificat din nou înainte de fiecare trimitere.

Când sosește. Starea este verificată cât timp plătitorul rămâne pe pagina de plată, care o consultă până la rezultatul final sau până la expirarea sesiunii de plată, și de fiecare dată când consulți POST /payments/?action=status. Nu există o trimitere programată separată: dacă plătitorul închide pagina înainte ca banca să finalizeze, sau dacă serverul tău nu răspunde cu 2xx, notificarea se trimite la următoarea verificare. De aceea, dacă nu ai primit notificarea la câteva minute după ce ai redirecționat plătitorul, consultă starea cu payment_intent_id; această interogare declanșează și notificarea în așteptare. Vezi Stări, interogare periodică și reconciliere.

Notificarea nu este semnată. Înainte de a livra un bun sau un serviciu valoros, confirmă rezultatul cu POST /payments/?action=status folosind X-API-Key a ta și payment_intent_id: doar payment_status: settled în acel răspuns reprezintă o confirmare financiară.