Maksete API integratsioon: tellimused, kordused ja kinnitused

Määra iga identifikaatori eesmärk

Tellimus, makse ja maksekatse ei ole alati üks ja sama objekt. Tellimus kirjeldab ostu, makseobjekt maksmist ning katse võib väljendada üht kliendi tegevust. Kui need mõisted on segamini, muutub korduva makse või pooleli jäänud katse uurimine kiiresti keeruliseks.

Kasuta stabiilset sisemist tellimuse viidet ja säilita teenuse vastusest saadud makse identifikaator. Näiteks võib üks tellimus sisaldada esimest katkestatud katset ja hilisemat kinnitatud makset. Tellimuse täitmise otsus peab arvestama kinnitatud tulemust, mitte viimati avatud brauseriakent. Dokumenteeri, millise identifikaatori järgi otsivad juhtumit arendaja, klienditugi ja raamatupidaja.

Arendustööriistad

Hoia hinnakontroll serveris

Klient võib saata serverisse toote valiku, kuid lõpliku summa peab kontrollima usaldusväärne rakendus. Ära võta makse loomiseks pimesi brauserist saadud summat. Kontrolli tellimuse kehtivust, valuutat ja seda, kas sama ost on juba tasutud või tühistatud.

Raha esitamise vorming tuleb võtta kasutatava API dokumentatsioonist. OrsunPay liidese täpne kümnendsumma ei pruugi vastata teise pakkuja näites kasutatavale ühikule. Lisa integratsiooni spetsifikatsiooni mõned konkreetsed näited ning kontrolli nende edasi-tagasi teisendamist. See väldib olukorda, kus tehniliselt edukas päring loob makse vale suurusega või vales valuutas.

Makseteenuse pakkujate ühendused

Planeeri idempotentsus enne korduskatseid

Võrgukatkestus võib jätta rakenduse teadmatusse: päring jõudis serverisse, kuid vastus ei jõudnud tagasi. Uue makse loomine täiesti uue päringuna võib siis tekitada duplikaadi. Idempotentsus võimaldab sama loogilist toimingut turvaliselt korrata vastavalt konkreetse API reeglitele.

Seosta võti ühe selgelt määratletud toiminguga ning salvesta see enne päringu saatmist. Ära kasuta sama võtit teise summa või teise tellimuse jaoks. Stripe dokumentatsioon aitab mõista põhimõtet, kuid OrsunPay puhul tuleb järgida selle enda liidese lepingut. Korduskatsete arv, ooteaeg ja lõpetamise tingimus peavad olema teadlikult määratud.

Töötle sündmusi eraldi vastusest

Makse loomise vastus võib anda järgmise sammu, mitte lõpliku tasumise kinnituse. Kliendi autentimine või makseviisi töötlus võib jätkuda hiljem. Seetõttu peab serveril olema võimalus võtta vastu kontrollitud webhook-sündmusi ning vajaduse korral makse olekut uuesti küsida.

Kontrolli allkirja kasutatava teenuse juhendi järgi ja säilita töötlemiseks vajalik minimaalne info. Sama sündmus võib korduda või saabuda ootamatul ajal. Tellimuse olekumuutus peab olema lubatud ja ühekordne. Kui sündmuse töötlemine ebaõnnestub, peab süsteem suutma seda uuesti töödelda ilma kliendile uut makset loomata.

Eralda keskkonnad ja õigused

Testkeskkonna võti, pärisrežiimi võti ja webhooki saladus täidavad erinevaid eesmärke. Neid ei tohi panna brauserikoodi ega avalikku lähtekoodi. Anna igale teenusele ainult vajalikud õigused ning lepi kokku, kuidas võtmeid vahetatakse ja kuidas mõjutab vahetus töötavaid ühendusi.

OrsunPay võimaldab kasutada ühist makseliigest, kuid kaupmehe leping ja konto makseteenuse pakkuja juures jäävad vajalikuks. Stripe ühenduse olemasolu ei tähenda kõigi teiste pakkujate automaatset tuge. Enne arenduse ajakava kinnitamist kontrolli kasutatavat ühendust, konto valmisolekut ning erinevusi testimise ja päris kasutuse vahel.

Kirjelda taastamine ja üleandmine

Koosta veajuhtumite tabel: aegunud päring, vigane summa, puuduv ühendus, korduv sündmus ning ajutiselt kättesaamatu tellimussüsteem. Iga rea juurde kirjuta, kas päringut korratakse, kas töö vajab inimest ning millise viite järgi juhtum leitakse. Veateade kasutajale ja tehniline logi ei pea sisaldama sama teavet.

Üleandmisel anna meeskonnale näidistellimused, olekute vastavustabel ja kontrollitud taastamisjuhis. Logides ei ole vaja säilitada kaardiandmeid ega kliendi kogu sõnumit. Hea integratsioon on selline, mille tõrke saab lahendada ka inimene, kes algset koodi ei kirjutanud. Selleks on vaja selgeid seoseid ja kontrollitavat ajalugu, mitte ainult edukat demonstratsiooni.

Koosta hooldatav integratsioonileping

Praktiline integratsioonileping võib olla lühike dokument, mis kirjeldab päringute sisendit, vastuste tähendust ja lubatud olekumuutusi. Lisa sinna näide edukast teekonnast ning eraldi näide kadunud vastusest. Kirjelda, kuidas rakendus leiab juba loodud makse, enne kui otsustab uut luua. Määra ka vead, mida ei tohi automaatselt korrata, näiteks vigane sisend või puuduv õigus. Dokument peab olema kättesaadav inimestele, kes süsteemi hiljem hooldavad. Kui muudetakse ühendust või API versiooni, vaadatakse läbi samad näited. Nii ei jää integratsiooni tegelik käitumine ühe arendaja mällu. Väikese ettevõtte jaoks võib see tähendada ainult mõnda selget lehekülge, kuid nende väärtus on suur siis, kui probleem tekib väljaspool tavapärast arendustööd.

Allikad

• Stripe API: idempotent requests
• Stripe Webhooks