Slik brukes Adyens tokenisering for å implementere abonnementer

Adyen tilbyr betalingstjenester til bedrifter som bruker abonnementsmodeller og andre gjentakende betalinger. Avhengig av behovene og forretningsmodellen deres, kan implementeringen av abonnementer se annerledes ut. Vurder følgende spørsmål:

• Vil dere ta betalt av kunden på månedsbasis?

• Når vil dere belaste kunden?

• Hva skal skje når en betaling mislykkes (f.eks. ikke nok penger på kontoen ved kjøp/betaling)?

La oss se nærmere på hvordan dere selv kan håndtere disse spørsmålene. 

Hvis dere ikke vil implementere og drive en abonnementstjeneste selv, kan vi hjelpe dere via våre partnere, som tilbyr tjenester som løser faktureringstjenester. Dere finner partnerne våre for dette på hjemmesiden vår.

Med Adyens tokeniseringsfunksjon kan dere enkelt håndtere gjentakende betalinger i diverse former ved at Adyen lagrer kortinformasjonen for dere, og i stedet får dere et Adyen-token som refererer til selve kortopplysningene. Prosessen kalles tokenisering. Det finnes tre måter å bruke tokener på:

• Engangsbetalinger: Enkelttransaksjoner der kortinnehaveren kan betale med betalingsopplysninger som er blitt lagret tidligere. Vi kaller denne gjentakende prosessen «CardOnFile» i API-en vår. For eksempel kan kortopplysningene være forhåndsutfylt ved kjøpet for å gjøre det enda enklere for kundene å handle.

• Abonnementer: Gjentakende transaksjoner som gjennomføres med jevne mellomrom for et produkt eller en tjeneste. Vi kaller denne gjentakende prosessen «Subscription» i API-en vår.

• Automatiske påfyllinger (og andre uregelmessig gjentakende avtaler): Avtaler der transaksjoner skjer uregelmessig ved hjelp av lagrede kortopplysninger. Dette omfatter for eksempel automatiske påfyllinger når kortinnehaverens saldo synker under et visst beløp. Vi kaller denne gjentakende prosessen «UnscheduledCardOnFile» i API-en vår.

I dette avsnittet ser vi nærmere på hvordan abonnementer fungerer, og hvilke hendelser som oppstår i forbindelse med betalingen mellom kortinnehaveren, forhandleren og Adyens plattform.

1. Etter en transaksjon på kundens initiativ (Customer Initiated Transaction) samler vi inn kortinformasjonen fra kunden.

2. Selgeren sender en første såkalt authorization request til Adyen for tokenisering. I denne fasen oppgir selgeren også en unik referanse som representerer denne kunden, også kalt Shopper reference.

3. Adyen svarer med authorization result.

Etter trinn 1 kan det være at kunden må gjennom en Strong Customer Authorization (SCA), der vedkommende identifiserer seg overfor kortinnehaverens bank. SCA er et krav i EU som skal gjøre nettbetalinger tryggere for forbrukere. Kravet gjelder betalinger på nettet i det økonomiske området EEA, Monaco og Storbritannia. Kravet innebærer i praksis at man ber om to av tre sikkerhetskontroller av forbrukerne: noe de vet, noe de eier og noe de er. Flere detaljer om kravet kan dere lese om i vår selvhjelpsveiledning.

4. Senere sender Adyen det ovennevnte tokenet og en såkalt Shopper reference via en asynkron melding (en «webhook») til forhandleren. Selgeren bør lagre dette tokenet og den tilknyttede «shopper reference». Disse to datapunktene brukes til å starte betalinger ved hver gjentakende fakturering.

5. Nå kan forhandleren i forhåndsbestemte intervaller starte en betaling på kundens vegne ved hjelp av et token og shopper reference. Dette kalles en Merchant Initiated Transaction (MIT).

Til slutt får forhandleren en asynkron melding (webhook) med resultatet av den initierte betalingen.

La oss se på hvordan dette ser ut i praksis ved hjelp av eksempelet vårt i en .NET-integrasjon. Vi har laget to perspektiver for vårt eksempel:

• Det ene perspektivet gjør det mulig for kunden å tokenisere betalingsopplysningene sine i den initierte betalingen.

• Det andre perspektivet gjør det mulig for en administrator å gjennomføre betalinger på forbrukerens vegne. I en kontinuerlig operativ virksomhet blir denne prosessen automatisert. I denne demonstrasjonen har vi latt administratoren utføre umiddelbare betalinger for kunden med et klikk.

En authorization request utføres gjennom et API-oppkall til sessions endpointen. I eksempelet nedenfor sender en forhandler en authorization request til Adyen, her ved hjelp av .NET-biblioteket. Slik ser C#-forespørselen ut:

Når kundens betalingsinformasjon er samlet inn, kan vi ta en titt på hvordan Adyen godkjenner en første authorization request og genererer et token. I dette eksempelet sender forhandleren verdien «0» (null) til Adyen.

Dette kalles Zero Auth og fører oss til neste emne: Dynamic Zero Auth.

Dynamic Zero Auth er særlig praktisk når forhandleren skal verifisere kortopplysningene og kortinnehaveren uten å ta betalt fra kjøperen. Dette kan være under en prøveperiode i en abonnementstjeneste eller for en pay-as-you-go-modell der kunden bare belastes for det som brukes. Ved å sende en Zero Auth-transaksjon til Adyen kan vi gjøre en autorisering med et nullbeløp. Når denne autoriseringen er akseptert, fungerer den som validering for selgeren at kjøperen er legitim.

Imidlertid støttes ikke Zero-Auth av alle kortutstedende banker. Visse banker krever spesifikke verdier for slike autoriseringer. Nederlandske iDeal, for eksempel, krever et beløp som er større enn null. Adyen løser dette problemet ved hjelp av Dynamic Zero Auth (også kjent som Dynamic Card Validation), som forhindrer at betalingen avvises, ved at verdien justeres automatisk til riktig beløp for autorisering.

Til slutt lagrer Adyen kortopplysningene på en sikker måte og oppretter et token (også kalt «recurringDetailReference»), som forhandleren bruker i fremtidige, gjentakende betalinger.

Tokener utløper aldri, men de kan deaktiveres manuelt via det vi kaller disable API-endpoint.

Når dere er klare til å ta betalt for et abonnement, ser forespørselen deres slik ut i C#.

Hvis betalingen er vellykket, belastes kunden, og tjenesten blir levert. Men hva skjer om authorization request mislykkes? Dette fører oss til de to neste emnene: Account Updater og Auto Rescue.

Når dere sender inn en betaling som av en eller annen grunn avvises (f.eks. utløpt kort), søker Adyen Real Time Account Updater umiddelbart etter oppdaterte kortdetaljer sammen med kortnettverkene (Visa, Mastercard osv.). Hvis det finnes et nytt kort, gjennomføres betalingen igjen umiddelbart, med de oppdaterte kortdetaljene. Alt dette skjer når betalingen behandles og vises som én enkelt transaksjon. Kortets token oppdateres også automatisk for å sikre at det refererer til de nyeste detaljene.

Adyen behandler også utløpte kort automatisk. Adyens Batch Account Updater leter automatisk opp det nyeste kortet som tilhører den aktuelle forbrukeren, slik at vi kan fortsette å belaste vedkommende selv om det gamle kortet er utløpt.

Adyens Auto Rescue vurderer avviste transaksjoner og chargebacks automatisk på nytt for transaksjoner der forbrukeren ikke er til stede, for eksempel ved fornying av abonnementer. Tjenesten bruker logisk resonnement til å bestemme hvilke betalinger som kan gjennomføres når de senere prøves på nytt, og utfører disse nye forsøkene på optimale tidspunkter.

En betaling kan avvises av mange forskjellige grunner. I enkelte tilfeller, når forbrukeren har for lite penger, kan betalingen likevel gjennomføres hvis den prøves på et senere tidspunkt. Hvis forbrukerens konto er avsluttet, avvises betalingen permanent.

Auto Rescue planlegger nye forsøk for avviste betalinger (eller chargebacks) som har en sjanse til å gjennomføres. Det kan ta flere forsøk å «redde» en betaling. Disse forsøkene skjer innen en viss tidsramme.

Etter en vellykket forespørsel om tokenisering sender Adyen et token via en asynkron webhook-melding. La oss se på hvordan vi bruker webhook-meldingen og får det nevnte tokenet (her kalt «recurringDetailReference») i koden. Slik ser C#-webhook-kommandoen ut:

Demonstrasjon

Dere finner eksempelet vårt på integrasjon for .NET på GitHub Start programmet ved å følge trinnene i readme. Når programmet har startet, ser dere to visninger: shopper-visning og Adyens administratorpanel.

1. I shopper-visningen kan forbrukeren kjøpe et musikkabonnement. Dette starter tokeniseringsprosessen.

2. I Adyens administratorpanel kan en administrator utføre en authorization request for forbrukeren eller velge å deaktivere et eksisterende token.

Dere finner deres lagrede tokener i administratorpanelet. Tenk på det som at programmet holder tokener i et lokalt minne. Når dere starter programmet på nytt, forsvinner tokenene.

I testprogrammet vårt får dere et administratorpanel for å starte betalinger på vegne av forbrukeren for å teste det. I et virkelig tilfelle ville det ikke være slik: Integrer forretningslogikken og bruk .NET-biblioteket til å fakturere kunder med forhåndsdefinerte parametre ved å initiere betalinger ved hjelp av token og tilknyttet kundereferanse.

Ved implementering av nye tjenester støter man fort på problemer. Til feilsøkingsformål har vi fremhevet noen av de vanligste problemene nedenfor.

La oss først sikre at dere aktiverer «Recurring details» i Webhooks. Under Additional data i kundeområdet må dere ha aktivert «Recurring details» (under «Payments») for å kunne ta imot meldingen som inneholder «recurringDetailReference». Denne referansen brukes til å starte betalinger i fremtiden. Nedenfor beskriver vi hvordan en vellykket og en mislykket webhook ser ut.

Vellykket webhook

Mislykket webhook

Error 803: Hvis dere får denne feilen etter å ha prøvd å utføre en gjentakende authorization request, betyr det at den lagrede kortinformasjonen (tokenet), som angis av recurringDetailReference, ikke er tilgjengelig for denne shopperReference. Enten finnes ikke recurringDetailReference, ellers så er ikke denne typen kontrakt konfigurert på riktig måte for denne recurringDetailReference.

Dobbeltsjekk hvilke flagg dere sender i dokumentasjonen. Dere kan når som helst sjekke hvilke kontraktstyper som er lagret for en bestemt shopperReference, ved å bruke endpointen paymentMethods eller listRecurringDetails.

Error 422: Hvis dere får denne feilen med feilkode «14_019», må dere angi korrekt recurringDetailReference i deres authorization request. Biblioteket skal automatisk gi dere riktig sdkVersion.

Problem med Adyens administratorpanel: Hvis ingenting vises i Adyens administratorpanel etter å ha gjort en authorization request i shopper view, kan dere feilsøke ved hjelp av listen nedenfor:

• Sikre at dere har gjennomført alle trinnene i vår readme.

• Er webhooken rettet mot riktig URL-adresse?

• Har dere konfigurert HMAC Key riktig? Hvis dere skriver inn en ugyldig nøkkel, mislykkes valideringen, og den mottatte meldingen blir ikke behandlet på riktig måte.

• Kjører dere på localhost? I så fall trenger dere en proxy for å gjøre det mulig for våre Adyen-servere å nå deres endpoint.

• Under «Additional Data» i kundeområdet deres må dere ha «Recurring details» (under Payments) for å få meldingen som inneholder deres «recurringDetailReference». Denne referansen brukes til å gjøre fremtidige authorization requests.

• Ta en titt på feilmeldingene deres i konsollen/terminalen.

Hvis dere har testet alle ovenstående trinn uten hell, kan dere åpne en forespørsel på GitHub.

Sammendrag

I denne veiledningen har dere lært hvordan man bruker Adyens tokenisering for å implementere abonnementer på .NET og hvordan dere kan:

1. Samle inn kundenes kortinformasjon.

2. Hente recurringDetailReference asynkront.

3. Opprette en authorization request med recurringDetailReference på vegne av kunden.

Vi prøver alltid å forbedre integrasjonseksempelet og skalere det til flere språk som er relevante for forhandlerne våre. Ta en titt i GitHub repository i dag og fortell oss hvordan vi kan bli bedre. Ellers så kan dere gjerne åpne en forespørsel på GitHub, og så bretter vi opp ermene!