Sådan bruges Adyens tokenisering til at implementere abonnementer i .NET

Adyen tilbyder betalingstjenester til virksomheder, der arbejder med abonnementsmodeller og andre tilbagevendende betalinger. Afhængigt af jeres behov og forretningsmodel kan implementeringen af abonnementer se forskellig ud. Tænk over følgende:

• Ønsker I betaling fra kunden på månedsbasis?

• Hvornår vil I opkræve penge fra kunden?

• Hvad skal der ske, når en betaling mislykkes (f.eks. hvis der ikke er nok penge på kontoen på købs-/betalingstidspunktet)?

Lad os se nærmere på, hvordan I selv kan løse disse problemer. 

Hvis I ikke ønsker selv at implementere og drive en abonnementstjeneste, kan vi hjælpe jer via vores partnere, der tilbyder løsninger til faktureringstjenester. I finder vores partnere på området på vores hjemmeside.

Med Adyens tokeniseringsfunktion kan I nemt administrere tilbagevendende betalinger i forskellige former, eftersom Adyen gemmer kortoplysningerne for jer, og I modtager en Adyen Token, der henviser til de faktiske kortdata. Processen kaldes tokenisering. Tokens kan bruges på tre måder:

• Engangsbetalinger: Enkelte transaktioner, hvor kortindehaveren kan betale med sine tidligere gemte betalingsoplysninger. Vi kalder denne tilbagevendende proces for "CardOnFile" i vores API. Eksempelvis kan kortdata være udfyldt på forhånd ved købet for at gøre det endnu nemmere for kunder at handle.

• Abonnementer: Tilbagevendende transaktioner, der udføres med jævne mellemrum for et produkt eller en tjeneste. Vi kalder denne tilbagevendende proces for "Subscription" i vores API.

• Automatiske 'optankninger' (og andre uregelmæssige tilbagevendende aftaler): Aftaler med uregelmæssige transaktioner ved hjælp af lagrede kortdata. Det omfatter f.eks. automatiske optankninger, når kortholderens saldo kommer under et bestemt beløb. Vi kalder denne tilbagevendende proces for "UnscheduledCardOnFile" i vores API.

I dette afsnit ser vi nærmere på, hvordan abonnementer ser ud, og hvordan betalingen forløber hos kortholderen, forhandleren og på Adyens platform.

1. Efter en kundeinitieret transaktion (Customer Initiated Transaction) indsamler vi kortinformation fra kunden.

2. Sælgeren sender en såkaldt authorization request til Adyen til tokenisering. På dette stadie anfører sælgeren også en unik reference, som repræsenterer den pågældende kunde, også kaldet Shopper reference.

3. Adyen svarer med authorization result.

Efter trin 1 skal kunden muligvis gennemgå en Strong Customer Authentication (SCA), hvor kunden identificerer sig over for kortindehaverens bank. SCA er et krav i EU med det formål at gøre onlinebetalinger mere trygge for forbrugere. Kravet gælder onlinebetalinger i det økonomiske område EEA, Monaco og Storbritannien. I praksis betyder kravet, at man beder om to ud af tre sikkerhedstjek fra forbrugeren: noget, de ved, noget, de ejer og noget, de er. I kan få flere detaljer om kravet i vores selvhjælpsguide.

4. På et senere tidspunkt sender Adyen det førnævnte token og en såkaldt Shopper reference via en asynkron besked (en "webhook") til forhandleren. Sælgeren skal gemme dette token og den tilknyttede ‘shopper reference’. Disse to datapunkter bruges til at igangsætte betalinger på hver tilbagevendende faktura.

5. Nu kan forhandleren, med forudbestemte intervaller, initiere en betaling på vegne af kunden ved at bruge token og shopper reference. Dette kaldes for en Merchant Initiated Transaction (MIT).

Som afslutning får forhandleren en asynkron meddelelse (webhook) med resultatet af den initierede betaling.

Lad os se, hvordan det ser ud i praksis gennem vores eksempel i en .NET-integration. Vi har implementeret to visninger for vores eksempel:

•  Den ene visning giver jeres kunde mulighed for at tokenisere sine betalingsoplysninger i den påbegyndte betaling.

• Et andet perspektiv er, at en administrator kan foretage betalinger på vegne af forbrugeren. I en produktionsvirksomhed ville denne proces være automatiseret. I demoen har vi givet administratoren mulighed for at foretage øjeblikkelige betalinger til kunden med ét klik.

Jeres authorization request udføres gennem API-signal mod sessions endpointen. I eksemplet nedenfor sender en forhandler en authorization request til Adyen, her ved hjælp af .NET-biblioteket. Sådan ser C#-anmodningen ud:

Nu hvor kundens betalingsoplysninger er indsamlet, skal vi se på, hvordan Adyen godkender en indledende authorization request og genererer en token. I dette eksempel sender forhandleren værdien "0" (nul) til Adyen.

Dette kaldes Zero Auth og fører os til næste emne: Dynamic Zero Auth.

Dynamic Zero Auth er særligt anvendeligt, når forhandleren har brug for at verificere kortoplysninger og kontoindehaver, uden at køberen skal betale. Det kan være i en prøvemåned for en abonnementstjeneste eller for en pay-as-you-go-model, hvor kunden kun debiteres for det, der bruges. Ved at sende en Zero Auth-transaktion til Adyen kan vi lave en autorisation med et beløb på nul. Når denne tilladelse accepteres, fungerer den som en validering for sælgeren af, at køberen er legitim.

Zero-Auths understøttes dog ikke af alle kortudstedende banker. Nogle banker kræver specifikke værdier for disse autorisationer. Hollandske iDeal kræver for eksempel et beløb, der er større end nul. Adyen løser dette problem ved at bruge Dynamic Zero Auth (også kendt som Dynamic Card Validation) til at forhindre en afvist betaling ved automatisk at justere værdien til det korrekte beløb for godkendelsen.

Til sidst gemmer Adyen kortoplysningerne sikkert og opretter en token (også kaldet "recurringDetailReference"), som forhandleren kan bruge til at foretage fremtidige tilbagevendende betalinger.

Tokens udløber aldrig, men de kan deaktiveres manuelt via det, vi kalder disable API-endpoint.

Når I er klar til at opkræve betaling for et abonnement, ser jeres anmodning sådan ud i C#.

Hvis betalingen går igennem, opkræves kunden og tjenesten leveres. Men hvad sker der, hvis jeres authorization request mislykkes? Det fører os videre til de næste to emner: Account Updater og Auto Rescue.

Når I indsender en betaling, der er afvist af forskellige årsager (f.eks. et udløbet kort), søger Adyen Real Time Account Updater med det samme efter opdaterede kortoplysninger sammen med kortnetværket (Visa, Mastercard, etc). Hvis der er et nyt kort, foretages betalingen straks igen med de opdaterede kortoplysninger. Alt dette sker, når betalingen behandles og vises som en enkelt transaktion. Kortets token opdateres også automatisk for at sikre, at det refererer til de seneste oplysninger.

Adyen håndterer også udløbne kort automatisk. Adyen Batch Account Updater finder automatisk det seneste kort, der tilhører den specifikke forbruger, så vi kan fortsætte med at opkræve forbrugeren, selvom deres gamle kort er udløbet.

Adyens Auto Rescue omprøver automatisk afviste transaktioner og chargebacks for transaktioner, hvor forbrugeren ikke er til stede, som f.eks. fornyede abonnementer. Tjenesten bruger logisk ræsonnement til at afgøre, hvilke betalinger der kan udføres, når de gentestes på et senere tidspunkt, og udfører disse gentests på optimale tidspunkter.

En betaling kan afvises af mange forskellige årsager. I nogle tilfælde, hvor forbrugeren har for få penge, kan betalingen stadig gennemføres, hvis den testes på et senere tidspunkt. Hvis forbrugerens konto er blevet lukket, bliver betalingen permanent afvist.

Auto Rescue planlægger nye forsøg på afviste betalinger (eller chargebacks), som har en chance for at blive gå igennem Det kan tage flere forsøg at "redde" en betaling. Disse forsøg sker inden for en vis tidsramme.

Efter en vellykket anmodning om tokenisering sender Adyen et token via en asynkron webhook-meddelelse. Lad os se på, hvordan vi bruger webhook-beskeden og får det nævnte token (her kaldet "recurringDetailReference") i koden. Sådan ser C# webhook-kommandoen en ud:

Demo

I kan finde vores eksempel på integration til .NET på GitHub. Start programmet ved at følge fremgangsmåden i readme. Når applikationen er startet, vil I se to visninger: shopper view og Adyen-administratorpanelet.

1. I shopper-visningen kan forbrugeren købe et musikabonnement. Dette starter tokeniseringsprocessen.

2. I Adyen-administratorpanelet kan en administrator udføre en autorisationsanmodning for forbrugeren eller vælge at deaktivere et eksisterende token.

I kan finde jeres gemte tokens i administratorpanelet. Husk, at applikationen gemmer tokens i en lokal hukommelse. Når I genstarter programmet, forsvinder tokens.

Vores testapplikation giver jer et administratorpanel til at starte betalinger på vegne af forbrugeren dog udelukkende til testformål. I det virkelige liv ville det ikke være tilfældet: Integrer forretningslogikken, og brug .NET-biblioteket til at fakturere kunden med foruddefinerede parametre ved at starte betalinger ved hjælp af en token og den tilknyttede kundereference.

Når man implementerer nye tjenester, kan man nemt løbe ind i problemer. Vi har angivet nogle af de mest almindelige problemer nedenfor med henblik på fejlfinding.

Lad os først sørge for, at I aktiverer "Recurring details" i Webhooks. Under Additional data i jeres kundeområde skal I have aktiveret Recurring details" (under “Payments”) for at modtage beskeden med jeres "recurringDetailReference". Denne reference bruges til at initiere betalinger i fremtiden. Nedenfor beskriver vi, hvordan et vellykket og mislykket webhook ser ud.

Vellykket webhook

Mislykket webhook

Error 803: Hvis I får denne fejl efter at have forsøgt at udføre en tilbagevendende authorization request betyder det, den lagrede kortinformationen (token), som angives af recurringDetailReference, ikke er tilgængelig for denne shopperReference. Enten findes recurringDetailReference ikke, eller også er denne type af kontrakt ikke korrekt konfigureret for denne recurringDetailReference.

Tjek gerne en ekstra gang hvilke flag, I sender i dokumentationen. I kan altid kontrollere, hvilke kontrakttyper der er lagret for en specifik shopperReference ved at bruge endpointen paymentMethods eller listRecurringDetails.

Error 422: Hvis I får denne fejl med fejlkoden '14_019', skal I angive korrekt recurringDetailReference i jeres authorization request. Biblioteket bør automatisk forsyne jer med de rette sdkVersion.

Problem med Adyens administratorpanel: Hvis der ikke vises noget i Adyens administratorpanel, når I har lavet en autorisationsanmodning i shopper view, kan I fejlfinde ved hjælp af listen nedenfor:

• Sørg for at sikre, at I har gennemført alle trin i vores readme.

• Peger webhooken til den rigtige URL?

• Har I konfigureret jeres HMAC Key korrekt? Hvis I indtaster en ugyldig nøgle, mislykkes valideringen, og den modtagne meddelelse vil ikke blive behandlet korrekt.

• Kører I på localhost? Hvis det er tilfældet, skal I bruge en proxy, så vores Adyen-servere kan nå jeres slutpunkt.

• Under "Additional Data" i jeres kundeområde skal I have "Recurring details" (under Payments) for at modtage meddelelse, som indeholder jeres "recurringDetailReference". Denne reference bruges til at lave fremtidige authorization requests.

• Se efter i jeres fejlmeddelelser i jeres konsol/terminal.

Hvis I har prøvet alle ovenstående trin uden held, bør I åbne en ticket på GitHub.

I denne guide har I lært, hvordan I bruger Adyens tokenisering til at implementere abonnementer i .NET, og hvordan I kan:

1. Indsamle kundernes kortoplysninger.

2. Hente recurringDetailReference asynkront.

Oprette en authorization request med recurringDetailReference for kundens regning.

Vi forsøger altid at forbedre integrationseksemplet og skalere det til flere sprog, der er relevante for vores forhandlere. Kig forbi vores GitHub repository i dag, og fortæl os, hvad vi kan gøre bedre. Alternativt kan I oprette en ticket på GitHub, så følger vi sagen til dørs!