Betalings-API: lav en integrationsaftale før det første kald

Definér identiteten for ordre og betalingsforsøg

En ordre og et betalingsforsøg er forskellige objekter. Den samme ordre kan kræve en ny betaling efter en dokumenteret fejl, mens et gentaget netværkskald kan være den samme operation. Definér derfor en intern ordreidentitet, en identitet for forsøget og den reference, integrationen returnerer. Beskriv relationen i et kort eksempel, som support kan forstå. Når en kunde spørger til en bestilling, skal medarbejderen kunne finde alle relevante forsøg uden at sammenblande dem. Undgå at bruge kundens e-mail som teknisk identitet. Den kan ændres, deles mellem bestillinger og indeholde personoplysninger, der ikke behøver stå i en log.

Udviklerværktøjer

Behandl beløb og valuta som en samlet beslutning

Fastlæg beløbet på serveren ud fra den godkendte ordre, og send valutaen eksplicit. Brug den præcision og det format, som den konkrete API kræver. OrsunPays dokumentation beskriver eksakte decimalbeløb; kopier ikke en anden udbyders beløbsformat uden at kontrollere forskellen. Lav eksempler med en almindelig ordre, en justeret ordre og en valuta, som virksomheden faktisk skal bruge. Beskriv også afrundingsreglen uden at gøre browseren ansvarlig for den endelige sum. Hvis et beløb ikke kan repræsenteres korrekt, bør integrationen stoppe og give en forståelig intern fejl frem for at sende en tilnærmet værdi videre.

Udbyderforbindelser

Aftal hvad et gentaget kald betyder

Netværket kan fejle, efter modtageren har behandlet en forespørgsel. Et nyt kald kan derfor skabe en ny operation, hvis integrationen ikke genkender gentagelsen. Stripe beskriver idempotente forespørgsler som et selvstændigt API-princip. Detaljer som nøglernes gyldighed og fejlbehandling skal læses i den anvendte dokumentation; de kan ikke overføres automatisk til OrsunPay. I egen applikation bør samme forretningsoperation have en stabil identitet, mens ændrede forudsætninger behandles bevidst. Notér, hvem der afgør, om et forsøg må gentages. Et ukendt udfald er ikke det samme som en afvist betaling og bør ikke udløse blind genoprettelse.

Byg en lille model for betalingsstatus

Beskriv de tilstande, applikationen skal kunne håndtere, med ord som medarbejderne forstår. Der kan være forskel på oprettet, afventende, bekræftet og mislykket, men de præcise felter afhænger af API-kontrakten. Knyt hver kendt tilstand til en tilladt handling. Eksempelvis må en bekræftet ordre gå videre til levering, mens et ukendt udfald kræver undersøgelse. Registrér tidspunktet for seneste verificerede oplysning og kilden til den. En lokal fejltekst må ikke overskrive en senere, gyldig bekræftelse. Aftal også, hvordan systemet indhenter en aktuel status, når et forventet webhook ikke er blevet behandlet.

Adskil hemmeligheder og driftsoplysninger

API-nøgler hører til i serverens kontrollerede konfiguration. De bør ikke indsættes i frontend-kode, supportbeskeder eller almindelige analysehændelser. Log i stedet sikre operationelle referencer, fejltyper og tidspunkter, som gør en undersøgelse mulig. Hold test- og liveforbindelser tydeligt adskilt, og dokumentér hvilke funktioner der faktisk findes i hver tilstand. OrsunPays betalingslinks i merchant cabinet er for eksempel live-only. En vellykket test i et andet miljø beviser derfor ikke, at alle handlinger er identiske. Gennemgå nøgleudskiftning og adgang for nye medarbejdere som en del af overdragelsen, så løsningen ikke afhænger af én udviklers personlige opsætning.

Overdrag en afgrænset integration til drift

OrsunPay samler understøttede betalingsoperationer gennem et fælles softwarelag, mens virksomheden beholder sine egne udbyderkonti og aftaler. Automatisk cascading og omkostningsoptimeret routing er ikke en nuværende funktion. Afslut integrationen med en gennemgang af normal betaling, gentaget forespørgsel, forsinket hændelse og manglende adgang. For hver situation skal drift vide, hvilke referencer der skal findes, og hvornår en udvikler eller udbyder kontaktes. Offentlig SDK-udgivelse er et særskilt spørgsmål fra kode i et repository. Vælg derfor dokumenterede endepunkter og bekræftede leverancer som grundlag frem for at planlægge efter en pakke, der endnu ikke er offentliggjort.

Kilder

• Stripe API: idempotent requests
• Stripe Webhooks