Betalnings-API: definiera order, försök och säkra upprepningar

Ge order och betalningsförsök skilda identiteter

Samma order kan ha flera betalningsförsök, medan ett upprepat nätverksanrop kan avse exakt samma operation. Definiera en intern orderidentitet, en identitet för försöket och referensen från betalningsintegrationen. Visa sambandet med ett exempel som kundservice förstår. När kunden frågar om en beställning ska medarbetaren kunna hitta relevanta försök utan att gissa utifrån belopp och klockslag. E-postadress är inte lämplig som enda teknisk nyckel, eftersom den kan ändras och återkomma i många köp. Spara stabila relationer på servern. Det gör både vanlig uppföljning och undersökning av okända resultat tydligare och minskar behovet av att sprida personuppgifter i felsökningsanteckningar.

Utvecklarverktyg

Bestäm beloppsformatet före det första anropet

Kontrollera belopp och valuta mot den godkända ordern. Använd den representation och precision som API-kontraktet anger. OrsunPay beskriver exakta decimalbelopp; andra produkter kan använda andra format. Låt därför inte en vana från en tidigare integration styra den nya utan kontroll. Ta fram exempel för ett normalt köp, ett ändrat belopp och de valutor företaget faktiskt ska använda. Bestäm hur avrundning hanteras och var ogiltiga värden stoppas. Webbläsaren kan visa priset, men servern bör kontrollera det slutliga underlaget. En begriplig intern felhantering är bättre än att skicka vidare ett ungefärligt värde som senare behöver förklaras för både kund och ekonomiansvarig.

Leverantörsanslutningar

Skilj upprepning från en ny affärsoperation

Ett timeoutfel bevisar inte att mottagaren misslyckades med att skapa betalningen. Därför måste teamet kunna upprepa samma operation på ett kontrollerat sätt utan att oavsiktligt starta en ny. Stripe dokumenterar idempotenta förfrågningar, men detaljer om nycklar och fel ska läsas i dokumentationen för den faktiska integrationen. I den egna applikationen behöver affärsoperationen en stabil identitet, medan ändrade förutsättningar hanteras medvetet. Bestäm vem som får avgöra att ett nytt försök behövs. Om utfallet är okänt ska befintlig referens och aktuell status undersökas först. En ny betalning är inte en generell lösning på alla typer av nätverksfel eller försenade svar.

Knyt varje status till en tillåten handling

Välj interna ord som verksamheten förstår och koppla dem till dokumenterade API-statusar. En operation kan vara skapad, väntande eller bekräftad, men exakta fält måste hämtas från kontraktet. Beskriv vad systemet får göra i varje läge. En verifierad betalning kan frigöra ordern, medan ett okänt utfall kräver utredning. Registrera källa och tidpunkt för den senaste kontrollerade uppgiften. Ett lokalt felmeddelande bör inte utan vidare skriva över ett senare giltigt resultat. Beskriv också hur aktuell status hämtas när en förväntad händelse saknas. Då finns en väg vidare som inte bygger på att alla meddelanden alltid kommer snabbt och i den ordning teamet hoppas.

Håll hemligheter åtskilda från driftsloggen

API-nycklar hör hemma i kontrollerad serverkonfiguration och ska inte hamna i webbläsarkod, supportmeddelanden eller analysverktyg. Logga säkra referenser, feltyper och tidpunkter som gör en undersökning möjlig. Tilldela behörigheter efter uppgift och beskriv hur nyckelbyte hanteras. Håll test och live tydligt åtskilda. Funktioner kan skilja sig mellan lägena; betalningslänkar i OrsunPays merchant cabinet hanteras exempelvis bara i liveläge. En lyckad genomgång av testmiljön innebär därför inte att alla användaråtgärder finns där. Förklara skillnaderna vid överlämning så att nästa medarbetare inte försöker lösa en avsiktlig begränsning genom att ändra en fungerande anslutning eller använda fel konto.

Lämna över en konkret rutin tillsammans med koden

OrsunPay erbjuder ett gemensamt programvarulager för stödda betalningsoperationer medan företaget behåller egna leverantörskonton och avtal. Automatisk routning med cascading och kostnadsoptimering är inte tillgängliga funktioner i dag. Gå igenom normal betalning, upprepat anrop, försenad händelse och saknad behörighet före överlämningen. Drift behöver veta vilka referenser som finns, vad som kan göras säkert och när utvecklare eller leverantör kontaktas. Publik publicering av SDK-paket är en separat fråga även när implementation finns i ett repository. Bygg därför på dokumenterade ändpunkter och bekräftade leveranser. Gör ansvar och nästa steg tydliga också i situationer där systemet ännu inte kan ge ett slutgiltigt betalningsbesked.

Källor

• Stripe API: idempotent requests
• Stripe Webhooks