Maksu-API: käytännön suunnitelma yrityksen integraatiolle

Määritä tietomalli yhdessä liiketoiminnan kanssa

Erota tilaus, maksu ja maksuyritys jo suunnittelussa. Tilaus kuvaa ostosta, maksu maksamiseen liittyvää kohdetta ja yritys yhtä etenemistä prosessissa. Sama asiakas voi keskeyttää ensimmäisen yrityksen ja onnistua toisella. Näiden yhdistäminen yhdeksi epämääräiseksi tilaksi vaikeuttaa selvittämistä.

Sovi, mikä tunniste näkyy asiakaspalvelulle ja mikä tallennetaan teknisiin lokeihin. Palveluntarjoajan vastauksesta saatu tunniste pitää yhdistää yrityksen omaan tilaukseen pysyvästi. Asiakkaan sähköpostiosoite ei ole korvaava tekninen avain. Kun yhteys on selkeä, tapahtuma voidaan löytää myös silloin, kun eri työntekijät käsittelevät tilausta ja maksun jälkeistä palvelua.

Kehittäjätyökalut

Tarkista rahamäärät luotetussa ympäristössä

Palvelin laskee tai tarkistaa maksun lopullisen summan tilauksen perusteella. Selaimen lähettämä määrä ei riitä yksin, koska käyttöliittymä voi olla vanhentunut tai pyyntö virheellinen. Tarkista samalla valuutta ja se, ettei tilausta ole jo täytetty tai suljettu.

Käytä kyseisen API:n dokumentoimaa rahamäärän esitystä. OrsunPayn täsmällinen desimaalimuoto ei ole automaattisesti sama kuin toisen palvelun esimerkin yksikkö. Kirjaa rajapintakuvaukseen muutama tarkistettava summa ja odotettu arvo. Tarkista myös pyöristys sekä virheellinen syöte. Tekninen onnistuminen ei ole riittävä tulos, jos asiakas maksaa väärän summan tai tapahtuma päätyy väärään valuuttaan.

Maksupalveluyhteydet

Suunnittele idempotenssi ennen uudelleenyrityksiä

Jos pyyntö aikakatkaistaan, sovellus ei välttämättä tiedä, loiko palvelin maksun. Uuden maksun luominen uudella tunnisteella voi tällöin aiheuttaa päällekkäisen tapahtuman. Idempotenssi auttaa toistamaan saman loogisen toimenpiteen turvallisesti käytetyn rajapinnan sääntöjen mukaisesti.

Tallenna toiminnon avain ennen lähettämistä ja liitä se oikeaan tilaukseen. Älä käytä samaa avainta eri summaan tai toiseen ostoon. Stripe dokumentoi periaatteen omalle API:lleen, mutta OrsunPayn yhteydessä noudatetaan sen omaa sopimusta. Määritä myös uudelleenyritysten rajat ja viiveet. Kaikkia virheitä, kuten väärää syötettä tai puuttuvaa oikeutta, ei pidä yrittää automaattisesti loputtomiin uudelleen.

Erottele aloitus ja lopullinen vahvistus

Maksun luomisen vastaus voi antaa seuraavan toiminnon asiakkaalle eikä vielä kertoa lopullisesta onnistumisesta. Tunnistautuminen tai maksutavan käsittely voi jatkua sen jälkeen. Tilausjärjestelmän pitää pystyä vastaanottamaan myöhempi vahvistus sekä tarkistamaan tarvittaessa ajantasainen tila.

Webhook-ilmoituksen alkuperä tarkistetaan ennen kuin sen perusteella muutetaan tilausta. Toistuva ilmoitus ei saa avata palvelua tai lähettää tavaraa uudelleen. Tallenna käsittelyn tulos ja käytä sallittuja tilasiirtymiä. Näin selaimen, API-vastauksen ja ilmoituksen erilainen saapumisjärjestys ei johda ristiriitaiseen lopputulokseen tai asiakkaalta pyydettyyn tarpeettomaan uuteen maksuun.

Rajaa avaimet ja yhteydet

Salaiset API-avaimet kuuluvat palvelimelle ja asianmukaisesti hallittuun säilytykseen. Niitä ei laiteta julkiseen lähdekoodiin, selaimen asetuksiin tai esimerkkilokeihin. Erottele testi- ja tuotantoympäristö sekä määritä, kuka voi vaihtaa avaimet ja miten vaihto tehdään keskeyttämättä hallitsemattomasti käytössä olevaa yhteyttä.

OrsunPay yhdistää maksuprosessia ohjelmistotasolla. Kauppias tarvitsee edelleen oman maksupalveluntarjoajan tilin ja sopimuksen. Stripe-yhteyden olemassaolo ei tarkoita, että mikä tahansa muu tarjoaja on liitettävissä heti. Vahvista tarvittava yhteys ja toimintojen saatavuus ennen toteutusaikataulua. Myös julkisen SDK-paketin saatavuus on tarkistettava, jos suunnitelma perustuu sellaiseen eikä suoraan REST-rajapintaan.

Tee häiriöstä selvitettävä

Kirjaa virhetilanteista vähintään toiminto, turvallinen viite ja lopputulos. Koko asiakkaan viestiä tai maksutietoja ei tarvitse kopioida jokaiseen lokiin. Asiakaspalvelu tarvitsee ymmärrettävän tilan, kun taas kehittäjä tarvitsee riittävän teknisen jäljen ongelman rajaamiseen.

Laadi taulukko aikakatkaisusta, virheellisestä summasta, puuttuvasta yhteydestä ja epäonnistuneesta ilmoituksen käsittelystä. Jokaiselle tilanteelle määritetään, toistetaanko toiminto, tarkistetaanko tila vai tarvitaanko ihminen. Jos maksu on jo vahvistettu, korjaus voi kohdistua vain tilausjärjestelmään. Uusi maksuyritys ei ole yleinen ratkaisu kaikkiin integraation ongelmiin, ja ohjeen pitäisi tehdä tämä ero näkyväksi.

Luovuta ylläpidettävä kokonaisuus

Integraation luovutukseen kuuluvat tunnisteiden kuvaukset, tilojen vastaavuudet ja käytännön palautumisohje. Pyydä toista kehittäjää selvittämään yksi kontrolloitu häiriö näiden tietojen avulla. Jos hän tarvitsee alkuperäisen tekijän muistia jokaisessa vaiheessa, dokumentaatio ei vielä tue ylläpitoa.

Testaa myös sama pyyntö uudelleen, viivästynyt ilmoitus ja palvelimen uudelleenkäynnistys kesken käsittelyn. Kirjaa odotettu lopputulos yrityksen näkökulmasta: yksi tilaus, oikea summa ja yksi toimitus. Rajapinnan onnistunut vastaus on tekninen havainto, mutta toimiva maksuprosessi on liiketoiminnallinen kokonaisuus. Selkeä luovutus auttaa säilyttämään tämän eron myös seuraavan muutoksen ja uuden tiimin jäsenen aikana. Lisää ohjeeseen myös yhteyshenkilö ja menettely, jolla rajapinnan muutoksista tiedotetaan ylläpidolle ennen niiden käyttöönottoa.

Lähteet

• Stripe API: idempotent requests
• Stripe Webhooks