Dokumentation POST-API version 1.0

Transkript

1 Dokumentation POST-API version 1.0 1/10

2 Innehåll Innehåll...2 Detta dokument... 3 Revision... 3 Allmänt...3 Om POST-API lösningen...4 Allmänt...4 Beskrivning av POST-API från köparens perspektiv...4 Beskrivning av POST-API från butikens perspektiv... 5 Integrera din butik... 6 Så här testar du din integrering... 7 Eget utseende på betalningssidorna...7 FAQ/Felsökning...8 2/10

3 Detta dokument Revision Revision Revision Revision av Johan Brunius av Jonas Lundstedt av Jesper Nilsson och Jonas Lundstedt Allmänt Detta dokument beskriver hur POST-API lösningen fungerar för Payer:s betalplattform. Dokumentet är övergripande, se exempelkoden för mer exakt information om hur man programmatiskt kommer igång med betalsystemet. 3/10

4 Om POST-API lösningen Allmänt Denna lösning används för att enkelt kunna ta betalt via bankkort (Visa, MasterCard, Diners), faktura, via diektbank (Handelsbanken eller Föreningssparbanken) samt telefonbetalning. POST-API et innebär att webbshoppen bygger ihop ett XML-formulär med hjälp av diverse funktioner som Payer tillhandahåller. Formuläret innehåller information om butiken, köparen samt vad betalningen gäller. Efter att formuläret är skapat så postas det över till Payer där vi tar emot informationen och presenterar en betaldialog för köparen (kan exempelvis vara en faktura-, kort- eller bankbetalningsdialog). Genom vår adminwebb kan ni välja om betalsättet skall bestämmas genom parametrar som skickas med från butiken vid varje köp eller om de skall väljas i betaldialogen. Om ni väljer det senare har ni också möjligheten att direkt på adminwebben bestämma vilka betalsätt som skall vara tillgängliga för köparen. Köparen fyller i sina faktura- eller kortuppgifter, eller väljer bank (beroende på betalsätt), sedan presenterar Payer en del dialoger för köparen för att denne ska bekräfta sitt köp. En callback till webbshoppen sker där Payer meddelar att betalningen gått bra, shoppen gör det som ska ske vid ett lyckat köp (lägger en order exempelvis). Det sista som sker är att köparen får se en tack-sida (default) hos Payer eller att köparen om man så önskar kommer tillbaks till webbshoppen. Beskrivning av POST-API från köparens perspektiv Nedan beskrivs hur ett kortköp kommer att gå till från köparens perspektiv (butikens kund) 1. Köparen lägger en beställning och går till butikens betalningssida där köparen väljer betalsätt 2. Köparen väljer PAYER som betalsätt och klickar på vidare. 3. Köparen länkas över till PAYERs webserver som skyddas av SSL. Där får köparen ange vilket kort/bank han skall betala med, mata in sina kortuppgifter och sedan klicka på vidare. 4. PAYER kontrollerar mot banken att köparen har tillräckligt med pengar på sitt konto och sedan dras det belopp som köparen skall betala direkt från köparens konto. 5. Köparen får sedan se ett kvitto på betalningen, antingen från PAYERs webserver, eller från butikens webserver (inställning). 4/10

5 Beskrivning av POST-API från butikens perspektiv Köparen lägger en beställning och går till butikens betalningssida Butiken inluderar funktionsfilen payread_post_api i betalningssidan. Därefter anropas ett par olika metoder från payread_post_api och slutligen skapas ett formulär med ett antal olika hidden fält och som skall postas mot en URL som automatiskt skapas. Det viktigaste hidden fältet innehåller en XML-struktur där själva datat för köpet, checksumma samt olika inställningar ligger. Denna struktur skapas automatiskt när man använder de fördefinierade metoderna i payread_post_api. Efter att forumuläret är skapat så klickar köparen på en submitknapp (1) och datat postas då till PAYERs server där meddelandet packas upp kontrolleras att indatat stämmer (2), sedan visas ett formulär för köparen där det finns möjlighet att mata in kortuppgifter. Därefter får köparen se köpuppgifter och kan då kontrollera att det stämmer (3). Efter detta trycker köparen på ok(4) och PAYER kontaktar banken för att kontrollera att det finns pengar på kontot (5) 5/10

6 PAYER meddelar butiken att en reservation av pengarna har skett på köparens konto (en s.k. autorize) (6). Meddelandet sker genom att PAYER skickar ett anrop till en egendefinerad websida, URL till denna sida har skickats med som parameter i XML strukturen. Butiken svarar på den egendefinerade websidan med ett okej svar (7) och Payer går vidare och drar pengarna från kundens konto (8). Efter att detta har skett meddelar PAYER butiken på nytt att pengarna har blivit dragna från köparens konto (en s.k. settle) (9). Butiken skapar på nytt en egendefinerad sida och skickar med URL till denna som paratmeter i XML strukturen. Butiken svarar på nytt med ett okej svar.(10). Notera att i steg 10 (settle) så kan ni göra det som ska hända på er sida vid ett lyckat köp, alltså lägga en order, skicka ett mail eller dylikt. Köparen får upp ett kvitto på genomförd betalning, svarat kan antingen visas ut av PAYER (11) eller av butikens webserver (11). Detta går att ställa in genom en parameter som anges i XML strukturen. Integrera din butik Tänk på att för att integrationen skall fungera dina egendefinerade websidor som svarar på anrop från PAYER ha publikt IP nummer. Om du använder ett internt (t.ex /localhost/etc) kommer ditt testköp inte att kunna genomföras. För att enklast integrera din butik, rekommenderar vi att du skriver ut referensdokumentation för payread_post_api där du enkelt kan se vad metoder gör samt vilka indata som krävs för respektive metod. Dokumentationen hittar du i payread_post_api.html som finns i den här katalogen. Därefter rekommenderar vi att ni direkt tittar på ett funktionellt exempel Exempel finns för både php och asp i samma katalog som detta dokument. Du kan sedan kopiera över funktionalitet direkt från detta exempel till din egen butik. Tänk på att när du vill skicka iväg transaktioner skarpt, måste du anropa metoden set_test_mode(false). 6/10

7 Så här testar du din integrering Du bör testa din integration med två olika testkortnummer. Det ena är ett vanligt testkreditkort och det andra är ett s.k. 3dsecured enrolled card. Med detta menas att detta kort kräver en speciell kontroll mot banken. Payer stöder båda dessa två typer av kort med den skillnaden att ett 3DSecured enrolled card får upp en extra sida i betalflödet där den gör en extra kontroll mot banken. Vanligt testkortnummer VISA : valfritt datum och cvc-kod 3DSecured enrolled card VISA : lösenord: transfort, valfritt datum, cvc-kod Bankbetalningen och fakturabetalningar kan ej köras i testläge, bankbetalningar på grund av det inte stöds av Bankerna i dagsläget. Det bästa är att ni gör ett köp för ett väldigt lågt belopp och ser så att allt verkar fungera som det ska. Eget utseende på betalningssidorna Det finns möjlighet att ha sin logo i övre vänstra hörnet av betalningssidorna. Denna bild skall vara i gif format och vara 235 x 50 punkter stor. Det går även att ha egendefinerade färger på betalningssidorna så att sidorna blir mer lik din butik. I foldern Utseende så hittar du stylesheets samt en html-sida som heter utseende.html som ni kan använda som mall när ni editerar utseende på sidorna. Filerna som du kan editerar är stylesheet-filen style.css samt logobilderna logo.gif, path_r.gif och path_o.gif. När du är klar med detta, kan du maila oss logo.gif, path_l.gif, path_r.gif, path_0.gif, wait.gif samt style.css till logga@payer.se. 7/10

8 FAQ/Felsökning Q: Vad är 3-D Secure? A: Bankerna och kortbolagen har infört en ny teknik för att göra kortbetalningar på nätet säkrare för både säljare och köpare. Tekniken kallas med ett samlingsnamn 3-D Secure. Andra namn är Verified by Visa och MasterCard SecureCode. Svenska kort har nyligen börjat anslutas till den här nya tekniken. PAYER har tagit fram en lösning som stödjer 3-D Securetekniken, vi kallar det för POST_API. Namnet syftar på att det rör sig om ett API som ni kan använda för att göra transaktioner, informationen om transaktionen postas in från er site. Läs mer på Visas eller Mastercards egna siter om 3D-Secure och vad det innebär. Q: Kan jag se hur kortdialogen hos er ser ut? A: Ja, ni kan antingen se hur API\Post_api\utseende/utseende.html ser ut eller så kan du köra exempelkoden och göra ett testköp (se ovan hur man gör detta) för att se hur det ser ut. Q: Auth/Settle-filen returnerar false, varför det? A: Det är det absolut vanligaste problemet som man stöter på när man implementerar vår betallösning och det kan bero på en mängd olika saker. Vanligtvis är sökvägen till Auth eller Settle-filen fel, det kan saknas läs rättigheter eller så har ni lagt till kod på sidan som inte fungerar. Q: När jag provkör bankbetalningar så får jag upp en blank sida, eller ett certifikatfel. Vad beror det på? A: När man provar bankbetalningar så kan man ej köra dessa i testläge, då kommer det upp en blank sida när man kommer över till banken. Så ni måste alltså testa att göra ett skarpt köp som ni sedan kan kreditera. En annan sak som är bra att veta är att Handelsbankens bankbetalning fungerar inte om ni saknar bankid på er dator. Alltså om ni saknar bankid och provar handla så kommer ni att få något slags fel (beroende på webbläsare) hos banken. Detta kan man inte göra något åt utan det bästa är att prova med ett bankid installerat. Q: Vi har problem med köp som genomförs utan att vi får en bekräftelse alt. Vi har problem med dubbeldebiteringar. A: Om ni har orderhantering och logik på er tack-sida (vilket vi inte rekommenderar), det vill säga success_redirect_url, och denna sida inte är skyddad av ett SSL-certifikat så kommer era köpare att få upp en varningsruta. Detta beror på att webbläsaren som standard varnar när man går från en säker till en osäker sida. Dock är betalningen genomförd i det här läget och det innebär ingen som helst risk att gå till den osäkra sidan. Det man kan göra för att lösa det här problemet är att SSL-skydda er tack-sida. Detta sker genom att ni själva införskaffar ett eget SSL-certifikat. Information om SSL kan ni få hos ert webbhotell, Payer säljer ej SSL-certifikat och ger ej heller support för certifikat. För informationstext om varningsrutan, se foldern Startpaket/Resources/Security Alert Box/. Dubbeldebiteringar beror på att dera kunder inte går vidare från alert boxen, de blir osäkra och gör om köpet igen. 8/10

9 Q: Vi får XML parsing failure när vi kommer över till Payer. A: Detta beror på att den XML som ni skickar in innehåller fel, ni bör felsöka detta själva genom att titta på källkoden i filen webshop_page2 och där kan ni ta värdet som finns i variablen payread_data och base64-decoda detta för att få fram XML-datan. Sök på exempelvis Google för att hitta en web-baserad base64-decoder. Jämför sedan den XML som ni skickar in med exemplet som ni hittar i foldern Startpaket\API\Post_api\XML Example. Q: Bankbetalningar fungerar inte, min XML verkar ok men jag får i alla fall ett fel som säger att Amount must be over 0. A: Semikolon : är inte tillåtet i beskrivningsfältet vid bankbetalningar. Q: Vi har problem med direktbank via Handelsbanken. A: Handelsbanken fungerar endast med Internet Explorer samt med köp över 10 kr. Q: Fungerar er lösning i frames? A: Nej tyvärr inte, beroende på någonting som heter third-party cookies, som är något som de flesta webbläsare inte tillåter som standard. Se för mer information om cookies. Q: Fungerar telefonbetalning, faktura, direktbank, kort i andra länder? A: Endast kort fungerar utanför Sverige. Direktbank fungerar bara med Svenska banker, faktura och telefonbetalning fungerar inte utanför Sverige. Q: Vilka beloppsgränser finns det i betalsystemet? A: Det finns en generell övre gräns på SEK. 9/10

10 Kontakta Payer Behöver du hjälp med tekniska problem kan du skicka ett mail till Vid övriga ärenden eller funderingar var god kontakta Telefonnummer: Vid akuta driftstörningar, ring vår jourtelefon (vardagar mellan 17-22, samt helger 9-21): Lycka till med integreringen. / Payer 10/10