Billig frontend-API

MERK: Før du skal jobbe på en frontend (ny eller gammel), sett deg inn i Billig sikkerhetspolicy og relaterte dokumenter. Denne skal følges under utvikling såvel som i produksjon.

Generelt overblikk over kjøpsprosessen finnes på Billig Swedbank Pay. Dokumentasjon over databasen (som en frontend generelt har lesetilgang til) finnes på Billig database. De tekniske detaljene for selve kjøpsprosessen i nettbutikk finnes på denne siden. For utvikling mot frontend må man være kjent med og sette seg inn i kravene fra innløser.

Kjøpsform

Kjøpssiden (siste side brukeren ser i frontenden før kjøp) skal POSTes mot https://billettsalg.samfundet.no/pay, og inneholder følgende felter:

price_NNNN_count: Antall billetter som skal kjøpes fra prisgruppe NNNN (0-9).
membercard: Kortnummer billetten skal legges på. (Man kan også bruke cardnumber, men dette anbefales ikke, da nettlesere kan feiltolke dette som et sted å fylle inn kredittkort.)
email: Epostadressen billetten skal legges på. (Maksimalt én av membercard og email skal være satt for en gyldig ordre.)
ccno: Kortnummer (VISA/MasterCard).
exp_month: Utløpsmåned (1-12).
exp_year: Utløpsår, to siste siffer (00-99).
cvc2: CVC2-kode, typisk tre siffer.

Kjøpssiden kan sende følgende felt:

seat_NNNN_III: Valgt sete i billettgruppe, checkbox. Det må sendes med seat_NNNN_III for alle billetter i price_group med ticket_group med is_theater_ticket_group satt til true.
wheelchair-total: Antallet billetter i kjøpet som er til rullestolbrukere.

Kjøpsformen skal alltid sendes over TLS, slik at ingen kan endre POST-URLen i et man-in-the-middle-angrep. Den skal ikke lagre (hverken i lokal sesjon eller på server) eller på noen måte gjøre ikketriviell behandling av kortdata; sjekke kontrollsiffer og laste rett PNG fra okkupasjon er greit, legge kortnummeret inn i noen form for sesjonsstate er ikke greit.

pay vil gjøre all nødvendig inputvalidering, reservere billetter, sende folk videre osv.

Neste gang frontenden ser brukeren, er det på én av to sider; OK-siden eller feilsiden.

Merk at det kan ta litt tid for nettleseren å koble til https://billettsalg.samfundet.no/ (SSL-tilkoblinger tar merkbart mer tid enn ikke-SSL-tilkoblinger). www.samfundet.no gjør dette ved å vise et ikon hentet fra billettsalg-siden seint i bestillingsprosessen (rett etter at kortnummeret er vist inn), slik at nettleseren allerede har tilkoblingen oppe idet formen POSTes.

OK-side

OK-siden vises idet kjøpet er fullført, og billettene sendt på epost. URLen vil være på typen https://www.samfundet.no/arrangement/billetter/status/XXX,YYY.

XXX og YYY er billettnummer (med HMAC), minst ett men potensielt veldig mange. Disse kan brukes til å konstruere en link til en PDF der brukeren kan laste ned billettene sine om han/hun ikke ønsker å vente på eposten. URLen vil være http://billig.samfundet.no/pdf?ticket0=XXX&ticket1=YYY osv.

Feilside

Feilsiden er litt mer komplisert å implementere rett, primært fordi man har ganske mye informasjon som skal sendes videre uten å lage XSS-hull. URLen klienten kommer til vil være på formen https://www.samfundet.no/arrangement/billetter/handlekurv?bsession=XYZ.

XYZ er en sesjons-ID som slås opp i tabellen payment_error. De aktuelle feltene her er:

error: Sesjons-IDen (så du kan spørre med en WHERE).
owner_cardno: Brukerens kortnummer (kan være NULL).
owner_email: Brukerens epostadresse (kan være NULL).
message: Feilmeldingen, ikke HTML-enkodet.

Dessuten finnes det en tabell payment_error_price_group, som i en del tilfeller beskriver innholdet av brukerens handlekurv. Felter her er, for hver prisgruppe som ligger i handlekurven:

error: Sesjons-IDen.
price_group: Prisgruppenummer.
number_of_tickets: Antall billetter for denne prisgruppen (0-9).

Feilsiden må gjøre følgende:

Om raden ikke finnes i payment_error, gikk noe veldig feil under kjøpsprosessen mht. databasen. Vis i så fall en generisk feilmelding.
Om payment_error_price_group er tom, ikke vis noen handlekurv eller kjøpsform, bare feilmeldingen. (Dette vil typisk skje i tilfeller hvor det ikke er ment at brukeren skal prøve på nytt, for eksempel at noe gikk feil i den aller siste fasen men billettene er sendt per epost likevel.)
Om payment_error_price_group har minst én rad, fyll inn handlekurven med informasjon fra disse radene, fyll ut kortnummer- og epostfeltene om de finnes (kortnummer vil ikke bli lagret i databasen, så de feltene må stå på default), og vis feilmeldingen over handlekurven. På den måten får brukeren beskjed om hva som er feil, og umiddelbar mulighet til å fikse problemene.

I en del tilfeller vil parametrene være noe justert i forhold til det brukeren skrev inn; dette er ikke noe frontenden trenger å tenke på.

JavaScript-kapabel feilside

I perioder med mye last kan det å generere feilsiden på serveren være en kilde til last, og det kan være ønskelig å heller bruke en statisk side som kan caches. Billig har en mekanisme for dette som frontenden kan gjøre opt-in på for klienter som støtter JavaScript; da vil i stedet de aktuelle parametrene sendes som en kryptografisk signert streng i hash-delen av URLen. (Merk at man også må støtte APIet i forrige seksjon, spesielt siden dette ikke brukes for feil-URLer i epost.)

For å bruke JavaScript-APIet, inkludér https://billettsalg.samfundet.no/formscript med <script>. Det vil automatisk markere formen (den antar at den første formen på siden er den riktige) som JavaScript-kapabel, slik at backenden vet den kan bruke denne feilmekanismen. Om backenden rapporterer en feil, vil den sende brukeren tilbake til samme URL, men med en lang base64-streng etter #. Da vil samme JavaScript dekode base64-strengen, verifisere at signaturen er korrekt (slik at mekanismen ikke kan brukes til XSS) og fylle inn formen.

Det må være et sted å legge feilmeldingen; dette skal være en tom <div> med id="dynamic-error" og være skjult per default, altså style="display: none".

I noen situasjoner vil det ikke være aktuelt for brukeren å sende inn siden på nytt (se forrige underseksjon). I slike tilfeller vil scriptet gjøre følgende:

Teksten inni første <h1> vil bli byttet ut med «Feil».
Første <h2> vil bli skjult.
Alle elementer med klassen «hidden-if-error» vil bli skjult. Kjøpsformen o.l. burde wrappes i en <div> med en slik deklarasjon.
Alle elementer med klassen «shown-if-error» vil bli vist.

JavaScript-kapabel billettside

Som med feilsiden, kan det være gunstig å generere billettside (den som kommer etter et ferdig kjøp) fra JavaScript. Imidlertid er det litt mer formatering som skal til for å generere en korrekt billettside, så det kan ikke gjøres like helautomatisk.

Om du har aktivert JavaScript for feilsiden, vil du også automatisk få det for billettsiden (du kan ikke velge å bruke kun den ene). I stedet for å få en liste med billettnummer på slutten av URLen (f.eks. /1234500000,1234600000/) vil du få en liste med events med «e» foran, f.eks. /e1234,e1235/. Hvis så er tilfelle, må du inkludere https://billettsalg.samfundet.no/formscript med <script>, altså samme URL som forrige gang (den finner automatisk ut fra parameteret hva slags resultat den har fått). Denne vil dekode billettlisten den får fra backenden (ikke prøv å dekode den selv, da formatet kan endre seg uten forvarsel!) og så kalle JavaScript-funksjonen ticket_callback(), som du må ha definert før <script>-taggen. Denne får ett parameter, et JavaScript-objekt som i JSON-format vil se slik ut:

{
  "tickets": [
    {
      "ticketno": "98434300000",
      "price_group": 1234,
      "on_card": true
    },
    {
      "ticketno": "98434400000",
      "price_group": 1234,
      "on_card": false
    }
  ],
  "price_groups": {
    1234: {
      "name": "Medlem",
      "event": 555,
      "price": 200
    }
  },
  "events": { 
    555: {
      "name": "Kosearrangement",
      "timestamp": 1505750400
    }
  }
}

Merk at billetter enkodes som strenger (de kan være større enn Number), mens prisgrupper og arrangementer enkodes som tall. Pris er i hele norske kroner, og timestamps er i UTC (så eksempeldatoen er 2017-09-18 18:00:00 UTC+0200). Du er alltid garantert at prisgrupper og events som det refereres til er tilgjengelig, og at det er minst én billett, men du kan få flere felter enn det som er listet i eksempelet. Ingen tekst er HTML-escapet, så det må du sørge for å gjøre selv.

Lenker: Start, billig, billig stripe, billig generelt, billig payex, billig sikkerhetspolicy, billig stripe, billig swedbank pay