Fast Track -maksut

Maksaja avaa URL:n ja hyväksyy maksun pankissaan. Taustalla luodaan sama muuttumaton maksuaikomus kuin muualla API:ssa: summa, maksunsaaja ja viesti lukitaan ennen kuin mitään päätyy selaimeen, ja Idempotency-Key-otsake estää toisen veloituksen, jos kutsu katkeaa.

Maksun luominen

POST /payments/?action=fast-track

Pakolliset otsakkeet: Content-Type: application/json, X-API-Key ja Idempotency-Key. Avaimen pituus on 16–128 merkkiä, se alkaa kirjaimella tai numerolla ja saa sisältää vain kirjaimia, numeroita ja merkkejä . _ : -; UUID v4 kelpaa. Jos se puuttuu tai sen pituus ei kelpaa, vastaus on 400 idempotency_key_required; jos siinä on muita merkkejä, 422 invalid_customer_reference. Avain on myös kauppiasviite: sitä ei tarvitse lähettää rungossa. Jos toistat saman avaimen samalla rungolla, saat saman URL:n uudelleen. Jos käytät sitä uudelleen eri tiedoilla, vastaus on 409 idempotency_conflict.

Kaikki kentät ovat pakollisia paitsi logo. Runko on sallittujen kenttien lista. Ylimääräinen kenttä tai puuttuva pakollinen kenttä palauttaa 422 invalid_request. logo on osa maksua: saman Idempotency-Key-avaimen toistaminen eri logo-arvolla on myös 409 idempotency_conflict.

Pikamaksulla ei ole omaa enimmäismäärää tässä API:ssa. Pankki hylkää maksun, jota se ei voi hyväksyä, myös summan perusteella, ja hylkäys saapuu KO-ilmoituksena osoitteeseen 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"
  }'

Vastaus, jonka tilakoodi on ensimmäisellä kerralla 201 ja 200, jos avain oli jo olemassa, sisältää URL:n ja maksun tunnisteen:

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

Ohjaa maksaja URL:iin. Token on fragmentissa, vanhenee widgetin mukana (yleensä 15 minuutissa) eikä sitä saa kirjata lokeihisi. Tallenna payment_intent_id tilauksesi yhteyteen.

OK- tai KO-ilmoitus

Kun Wealthreader tarkistaa maksun tilan ja toteaa sen lopulliseksi, se lähettää POST-pyynnön osoitteeseen notification_url otsakkeilla Content-Type: application/json ja 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 on ok vain, jos pankki on tilittänyt maksun (settled). rejected, cancelled, expired ja failed ilmoitetaan arvolla ko. Epäselvä tulos (reconciliation_required) ei ole lopullinen, eikä siitä ilmoiteta.
• customer_reference on Idempotency-Key-avaimesi ja payment_intent_id maksua luotaessa palautettu tunniste.
• Vastaa 2xx, jotta ilmoitus katsotaan toimitetuksi. Wealthreader odottaa enintään 3 sekuntia eikä seuraa uudelleenohjauksia.
• Sama ilmoitus voi saapua useammin kuin kerran: käsittele yhdistelmää customer_reference ja outcome idempotenttina.
• URL, joka ei ole julkinen https-osoite, hylätään maksua luotaessa, ja se tarkistetaan uudelleen ennen jokaista lähetystä.

Milloin ilmoitus saapuu. Tila tarkistetaan, kun maksaja on vielä maksusivulla, joka kyselee sitä lopulliseen tulokseen asti tai kunnes maksuistunto vanhenee, sekä aina, kun kutsut POST /payments/?action=status. Erillistä ajastettua lähetystä ei ole: jos maksaja sulkee sivun ennen kuin pankki on valmis tai jos palvelimesi ei vastaa 2xx, ilmoitus lähetetään seuraavan tarkistuksen yhteydessä. Jos et siis ole saanut ilmoitusta muutaman minuutin kuluttua maksajan uudelleenohjauksesta, tarkista tila payment_intent_id-tunnisteella; tämä kysely myös laukaisee odottavan ilmoituksen. Katso Tilat, tilakyselyt ja täsmäytys.

Ilmoitusta ei ole allekirjoitettu. Ennen kuin toimitat arvokkaan tuotteen tai palvelun, vahvista tulos kutsulla POST /payments/?action=status käyttäen X-API-Key-avaintasi ja payment_intent_id-tunnistetta: vain payment_status: settled kyseisessä vastauksessa on taloudellinen vahvistus.