Använd Adyen Tokenisering för att implementera prenumerationer

Adyen erbjuder betaltjänster för företag som arbetar med prenumerationsmodeller och andra återkommande betalningar. Beroende på era behov och er affärsmodell kan implementeringen för prenumerationer se annorlunda ut. Fundera på följande frågor:

• Vill du ta betalt av kunden på månadsbasis?

• När vill du dra pengar från kunden?

• Vad bör ske när en betalning misslyckas (t.ex. Inte tillräckligt med pengar på kontot vid köp/betalningstillfället)?

Låt oss titta närmare på hur ni själva kan hantera dessa frågor.  

Om ni inte vill implementera och driva en prenumerationstjänst själva kan vi hjälpa er via våra partners som erbjuder tjänster som löser faktureringstjänster. Ni hittar våra partners för detta på vår hemsida.

Med Adyens tokeniseringsfunktion kan ni enkelt hantera återkommande betalningar i dess olika former, genom att Adyen sparar kortinformationen åt er och ni istället får en Adyen Token som refererar till själva kortdatan. Processen kallas tokenisering. Det finns tre sätt att använda sig av tokens:

• Engångsbetalningar: Enskilda transaktioner där kortinnehavaren kan betala med sina tidigare sparade betalningsuppgifter. Vi kallar denna återkommande process "CardOnFile" i vårt API. Exempelvis kan kortdatan vara förifylld vid köptillfället för att ytterligare underlätta för kunderna att handla.

• Prenumerationer: Återkommande transaktioner som genomförs med jämna mellanrum för en produkt eller tjänst. Vi kallar denna återkommande process "Subscription" i vårt API.

• Automatiska påfyllningar (och andra oregelbundna återkommande överenskommelser): Avtal vars transaktioner sker oregelbundet med hjälp av lagrade kortuppgifter. Detta omfattar exempelvis automatiska påfyllningar när kortinnehavarens saldo sjunker under ett visst belopp. Vi kallar denna återkommande process "UnscheduledCardOnFile" i vårt API.

I denna sektion kommer vi titta närmare på hur prenumerationer ser ut och händelseförloppet för betalning med kortinnehavaren, handlaren och Adyens plattform.

1. Efter en kundinitierad transaktion (Customer Initiated Transaction) samlar vi in kortinformation från kunden.

2. Säljaren skickar en första s.k. authorization request till Adyen för tokenisering. I detta skede uppger säljaren även en unik referens som representerar denna kund, även kallat Shopper reference.

3. Adyen svarar med authorization result.

4. Vid en senare tidpunkt skickar Adyen tidigare nämnda token och en s.k. Shopper reference via ett asynkront meddelande (en ‘webhook’) till handlaren. Säljaren bör spara denna token och tillhörande ‘shopper reference’. Dessa två datapunkter används för att initiera betalningar vid varje återkommande fakturering.

5. Nu kan handlaren, med förbestämda intervaller, initiera en betalning åt kundens vägnar med hjälp av token och shopper reference. Detta kallas för en Merchant Initiated Transaction (MIT). 

Till slut får handlaren ett asynkront meddelande (webhook) med resultatet av den initierade betalningen. 

Hur ser detta ut i praktiken, genom vårt exempel i en .NET-integration? Vi har skapat två perspektiv för vårt exempel:

• Ett perspektiv tillåter er kund att tokenisera sina betalningsuppgifter i den initierade betalningen. 

• Ett annat perspektiv tillåter en administratör att genomföra betalningar åt konsumenten. I en löpande operativ verksamhet skulle denna process vara automatiserad. För demons syfte har vi tillåtit administratören att göra omedelbara betalningar åt kunden med ett klick.

Er authorization request utförs genom ett API-anrop mot sessions endpointen. I exemplet nedan skickar en handlare en authorization request till Adyen, här med hjälp av .NET-biblioteket. Så här ser C#-begäran ut:

Nu när kundens betalningsinformation har samlats in bör vi ta en titt på hur Adyen godkänner en första authorization request och genererar en token. I det här exemplet skickar handlaren värdet "0" (noll) till Adyen.

Detta kallas Zero Auth och leder oss till nästa ämne: Dynamic Zero Auth.

Dynamic Zero Auth är särskilt användbart när handlare behöver verifiera kortuppgifterna och kontoinnehavaren utan att ta betalt av köparen. Detta kan vara under en testmånad av en prenumerationstjänst eller för en pay-as-you-go-modell där kunden endast debiteras för det som används. Genom att skicka en Zero Auth-transaktion till Adyen kan vi göra en auktorisering med ett nollbelopp. När denna auktorisering accepteras fungerar den som en validering för säljaren att köparen är legitim.

Zero-Auths stöds dock inte av alla kortutgivande banker. Vissa banker kräver specifika värden för dessa auktoriseringar. Nederländska iDeal, till exempel, kräver ett belopp som är större än noll. Adyen löser detta problem med hjälp av Dynamic Zero Auth (även känt som Dynamic Card Validation) för att förhindra en nekad betalning genom att automatiskt justera värdet till rätt belopp för auktoriseringen.

Till sist lagrar Adyen kortuppgifterna på ett säkert sätt och skapar en token (även kallat "recurringDetailReference") som handlaren kommer att använda för att göra framtida återkommande betalningar.

Tokens upphör aldrig men de kan inaktiveras manuellt via vad vi kallar för disable API-endpoint.

När ni är redo att ta betalt för en prenumeration ser er förfrågan ut såhär i C#.

Om betalningen lyckas så debiteras kunden och tjänsten levereras. Men vad händer om er authorization request misslyckas? Detta för oss till nästa två ämnen: Account Updater och Auto Rescue.

När ni skickar in en betalning som nekas av olika skäl (t.ex. utgånget kort), söker Adyen Real Time Account Updater omedelbart efter uppdaterade kortuppgifter tillsammans med kortnätverken (Visa, Mastercard, etc). Om det finns ett nytt kort genomförs betalningen omedelbart igen med de uppdaterade kortuppgifterna. Allt detta sker när betalningen hanteras och visas som en enda transaktion. Kortets token uppdateras också automatiskt för att säkerställa att den refererar till de senaste detaljerna.

Adyen hanterar även utgångna kort automatiskt. Adyen Batch Account Updater letar automatiskt upp det senaste kortet som tillhör den specifika konsumenten så att vi kan fortsätta att debitera konsumenten även om deras gamla kort har gått ut.

Adyens Auto Rescue omprövar automatiskt nekade transaktioner och chargebacks för transaktioner där konsument inte är närvarande, till exempel förnyade prenumerationer. Tjänsten använder logiska resonemang för att bestämma vilka betalningar som kan genomföras när de testas igen vid senare tillfälle och utför dessa nya försök vid optimala tidpunkter.

En betalning kan nekas av många olika skäl. I vissa fall, när konsumenten  har för lite pengar, kan betalningen fortfarande genomföras om den testas vid ett senare tillfälle. Om konsumentens konto har avslutats nekas betalningen permanent.

Auto Rescue schemalägger nya försök för nekade betalningar (eller chargebacks) som har en chans att genomföras framgångsrikt. Det kan behövas flera försök för att “rädda” en betalning. Dessa försök sker inom en viss tidsram.

Efter en framgångsrik begäran om tokenisering skickar Adyen en token via en asynkron webhook-notifikation. Låt oss titta på hur vi använder webhook-meddelandet och skaffar nämnda token (här kallad "recurringDetailReference") i koden. Så här ser C# webhook-kommandot ut:

Demo

Du kan hitta vårt exempel på integration för .NET på GitHub. Starta programmet genom att följa stegen i readme. När applikationen har startat ser ni två vyer: shopper view och Adyens administratörspanel.

1. I shopper-vyn kan konsumenten köpa en musikprenumeration. Detta startar tokeniseringsprocessen.

2. I Adyens administratörspanel kan en administratör utföra en authorization request åt konsumenten eller välja att inaktivera en befintlig token.

Ni kan hitta era lagrade tokens i adminpanelen. Tänk på att applikationen håller tokens i ett lokalt minne. När ni startar om programmet försvinner tokens.

Vår testapplikation ger er en adminpanel för att initiera betalningar på uppdrag av konsumenten endast för teständamål. Vid ett verkligt fall skulle det inte vara fallet: integrera affärslogiken och använd .NET-biblioteket för att fakturera kunden med fördefinierade parametrar genom att initiera betalningar med hjälp av token och tillhörande kundreferens.

Vid implementering av nya tjänster är det lätt hänt att stöta på problem. Vi har markerat några av de vanligaste problemen nedan i felsökningssyfte.

Låt oss först säkerställa att ni aktiverar "Recurring details" i Webhooks. Under Additional data i ert kundområde måste ni ha "Recurring details" (under “Payments”) aktiverat för att ta emot meddelandet som innehåller er “recurringDetailReference”. Denna referens används för att initiera betalningar i framtiden. Nedan beskriver vi hur en framgångsrik och misslyckad webhook ser ut.

Framgångsrik webhook

Misslyckad webhook

Error 803: Om ni får det här felet efter att ha försökt utföra en återkommande authorization request betyder det att den lagrade kortinformationen (token), som anges av recurringDetailReference, inte är tillgänglig för denna shopperReference. Antingen finns inte recurringDetailReference eller så är denna typen av kontrakt inte korrekt konfigurerad för denna recurringDetailReference.

Dubbelkolla vilka flaggor du skickar i dokumentationen. Du kan alltid kontrollera vilka kontraktstyper som är lagrade för en specifik shopperReference, genom att använda endpointen paymentMethods eller listRecurringDetails.

Error 422: Om ni får det här felet med felkoden '14_019', ange korrekt recurringDetailReference i er authorization request. Biblioteket bör automatiskt förse er med rätt sdkVersion. 

Problem med Adyens administratörspanel: Om ingenting visas i Adyens administratörspanel efter att ha gjort en authorization request i shopper view kan ni felsöka med hjälp av nedanstående lista:

• Säkerställ att ni genomfört alla steg i vår readme. 

• Är webhook riktad mot rätt URL?

• Har ni konfigurerat er HMAC Key korrekt? Om ni skriver in en ogiltig nyckel kommer valideringen att misslyckas och den mottagna notifikationen kommer inte processas på ett korrekt sätt.

• Kör ni på localhost? Om så är fallet behöver ni en proxy för att tillåta våra Adyen-servrar att nå er endpoint.

• Under "Additional Data" i ert kundområde, måste ni ha "Recurring details" (under Payments) för att få meddelandet som innehåller er "recurringDetailReference". Denna referens används för att göra framtida authorization requests.

• Kika på era felmeddelanden i er konsol/terminal. 

Om ni har testat alla ovanstående steg utan framgång bör ni öppna ett ärende på GitHub

Sammanfattning

I denna guiden har ni lärt er hur man använder Adyens tokenisering för att implementera prenumerationer på .NET samt hur ni kan:

1. Samla in kundernas kortinformation.

2. Hämta hem recurringDetailReference asynkront.

3. Skapar en authorization request med recurringDetailReference för kundens räkning.

Vi försöker alltid förbättra integrationsexemplet och skala det till flera språk som är relevanta för våra handlare. Ta en titt i vårt GitHub repository idag och berätta hur vi kan förbättra oss. Alternativt, öppna gärna ett ärende på GitHub så kavlar vi upp ärmarna!