Betalings-API: avklar kontrakten mellom ordre og betaling

Gi ordre og forsøk forskjellige identiteter

En ordre kan ha flere betalingsforsøk, mens en gjentatt nettverksforespørsel kan gjelde nøyaktig samme operasjon. Definer derfor en intern ordreidentitet, en identitet for forsøket og referansen fra betalingsintegrasjonen. Vis sammenhengen med et enkelt eksempel som kundeservice kan lese. Når en kunde spør om en bestilling, skal medarbeideren finne relevante forsøk uten å gjette på beløp eller tidspunkt. E-postadresse er et dårlig valg som eneste tekniske identitet: den kan endres og brukes til mange bestillinger. Bruk stabile referanser og lagre sammenhengen på serveren. Det gjør både normal oppfølging og undersøkelse av et ukjent resultat mer presis.

Utviklerverktøy

Fastsett beløpsformatet før implementasjonen

Beløp og valuta skal kontrolleres mot den godkjente ordren. Bruk formatet og presisjonen som den aktuelle API-en dokumenterer. OrsunPay beskriver eksakte desimalbeløp; andre produkter kan bruke andre representasjoner. Ikke la en antakelse fra en tidligere integrasjon bestemme det nye formatet. Lag eksempler med en vanlig ordre, en justert sum og hver valuta bedriften faktisk skal bruke. Bestem også hvordan avrunding håndteres, og hvor et ugyldig beløp stoppes. Nettleseren kan vise en pris, men serveren bør kontrollere det endelige grunnlaget. En tydelig feilmelding internt er bedre enn at en omtrentlig eller feilformatert verdi sendes videre til betaling.

Leverandørtilkoblinger

Definer sikre gjentakelser av forespørsler

Et tidsavbrudd sier ikke alltid om mottakeren rakk å opprette betalingen. Derfor må teamet skille mellom å gjenta den samme operasjonen og å starte en ny. Stripe dokumenterer idempotente forespørsler som et API-prinsipp, men detaljer om nøkler og feil må kontrolleres i den integrasjonen som brukes. I egen applikasjon bør en forretningsoperasjon ha en stabil identitet, og endrede forutsetninger behandles bevisst. Avtal hvem som avgjør om et forsøk kan gjentas. En ukjent status er ikke en sikker avvisning. Finn eksisterende referanse og undersøk resultatet før en ny betaling opprettes som en generell løsning på alle nettverksproblemer.

Lag en enkel modell for betalingsstatus

Velg interne begreper som teamet forstår, og koble dem til de dokumenterte statusene i API-en. En operasjon kan for eksempel være opprettet, avventende eller bekreftet, men de konkrete feltene må hentes fra kontrakten. Knytt hver tilstand til tillatte handlinger. En verifisert bekreftelse kan frigjøre en ordre, mens et ukjent utfall krever undersøkelse. Registrer kilden og tidspunktet for siste kontrollerte opplysning. En lokal feilmelding bør ikke uten videre overskrive et senere gyldig resultat. Beskriv også hvordan applikasjonen henter aktuell status dersom en forventet hendelse ikke er behandlet. Det gir drift en vei videre når normal automatisering stopper.

Hold nøkler og kundedata utenfor vanlige logger

API-nøkler hører hjemme i kontrollert serverkonfigurasjon, ikke i nettleserkode, analysehendelser eller supportmeldinger. Logg sikre driftsreferanser, feiltype og tidspunkt som gjør undersøkelse mulig. Gi ansatte rettigheter etter oppgaven og dokumenter hvordan nøkkelbytte gjennomføres. Skill tydelig mellom test og live. Funksjoner kan være forskjellige i miljøene; OrsunPays betalingslenker i merchant cabinet er for eksempel live-only. En gjennomgang av testmiljøet beviser derfor ikke at alle brukerhandlinger finnes der. Sørg for at overleveringen forklarer disse forskjellene, slik at en ny medarbeider ikke feiltolker manglende funksjon som et tilfeldig driftsproblem eller endrer en fungerende forbindelse unødvendig.

Lever en driftsrutine sammen med koden

OrsunPay gir et felles programvarelag for støttede betalingsoperasjoner, mens bedriften beholder egne leverandørkontoer og avtaler. Automatisk cascading og kostnadsoptimalisert ruting er ikke tilgjengelige funksjoner i dag. Gå gjennom normal betaling, gjentatt forespørsel, forsinket hendelse og manglende tilgang før overlevering. For hvert tilfelle bør drift vite hvilke referanser som skal finnes, hva som kan gjøres trygt, og når leverandør eller utvikler kontaktes. Offentlig publisering av SDK-pakker er en egen leveranse, selv om implementasjonskode finnes. Basér derfor løsningen på dokumenterte endepunkter og bekreftet tilgjengelighet, og gjør neste ansvarlig i prosessen tydelig også når svaret ikke kommer som forventet.

Kilder

• Stripe API: idempotent requests
• Stripe Webhooks