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 PayEx. 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:

Kjøpssiden kan sende følgende felt:

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:

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:

Feilsiden må gjøre følgende:

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:

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 payex, billig sikkerhetspolicy

Mail: itk@samfundet.no | Telefon: 992 15 925 | Sist endret: 2018-10-26 00:32 | Revisjon: 20 (historie, blame) | Totalt: 1467 kB | Rediger