Betalings API (modul)

Hvad er Betalings API?

DanDomains Betalings API er en udvidelses app, som du kan tilkøbe gennem AppStore i webshoppens administration.

Du kan hente et eksempel script til Betalings API her

Appens formål er at give dig mulighed for at bruge eksterne betalings systemer (eller payment gateways), hvor DanDomain ikke i forvejen har lavet en indbygget integration i vores Webshop. De indbyggede integrationer er f.eks. DanDomains eget betalingssystem og PayPal (begge er apps du kan tilkøbe) og du kan evt finde flere muligheder i AppStore. Men hvis du ikke kan finde det du har brug for, så er betalings API din mulighed for selv at stå for en integration.

Det kan f.eks. være at du skal sælge til et andet land, hvor en bestemt type betalingsform er dominant. Eller måske har du bare fundet et billigere alternativ end NETS. Det kan sågar også være at du vil tilbyde en fakturerings service (ala Klarna i Sverige). Du kan i princippet bruge betalings API i alle situationer hvor du gerne vil have kundens køb til at fører til en anden kontekst og så tilbage til shoppen igen.

Enkelte Payment gateways kender allerede DanDomains webshop og kan derfor måske tilbyde dig et script de allerede har lavet på forhånd. Men langt de fleste vil ikke kende os og kan kun give dig oplysninger om hvordan du programmerer op imod dem. Opgaven med at kæde systemerne sammen er derfor ofte én du skal bruge en ekstern udvikler for at løse. DanDomain har en række partnere, der evt kan stå til hjælp her. Du kan finde mere om disse under webshoppen på dandomain.dk.

Som bruger af betalings API’et er du selv ansvarlig for funktionaliteten. Det er op til dig (eller en udvikler) at få integrationen til at fungere. DanDomain support kan hjælpe dig med de grundlæggende koncepter (som du også kan læse om her), men kan ikke supportere den løsning du ender med selv at implementere.

Hvordan fungerer det?

Rent teknisk fungerer Betalings API ved at du laver en betalingsmetode til formålet. Denne betalingsmetode får så mulighed for at du kan indsætte en URL til et script der skal håndtere integrationen (Det er som nævnt det script du har ansvaret for). Dette script skal ligge tilgængeligt på nettet et sted. Du kan uploade det til mediearkivet, hvis det bliver lavet i klassisk asp, men for andre scriptsprog som f.eks. php, skal du bruge et andet websted der understøtter dette. Det kan være at en udvikler du får ind over kan tilbyde at hoste det, men ellers kan du også kontakte DanDomain for mulighed for en hosting, der kan hjælpe dig.

Når kunden gennemfører et køb og har valgt betalingsmetoden, så bliver scriptet kaldt med så en masse såkaldte POST variabler. Det er alle de data der hører til ordren, som f.eks. totalbeløbet og ordrenummeret. Og det betyder at disse kan trækkes ud af scriptet og bruges i integrationen op imod Payment gatewayen. Du kan se en oversigt over disse tilgængelige variabler længere nede.

Det er så op til sciptet herfra at lave alt det eksterne der skal til for få integrationen til at virke. Helt klassisk kunne det f.eks. være at kalde et API ved payment udbyderen med beløb, valuta og ordre nummer, så disse er kendt når kunden efterfølgende viderestilles til deres betalingsvindue og kan indtaste kortdata.

Efter betalingen er gennemført skal ordren nu afsluttes og kunden skal ledes tilbage til shoppens bestil step 4 (ordrebekræftelse). Dette er skridt er også kendt som et “callback”. Èn mulighed er at levere callback URL til payment gatewayen, så denne selv afslutter ordren, men det er også muligt at et mellemled kan sættes ind imellem, hvis du selv ønsker at give meddelelser til kunden inden du så returnerer kunden til bestil step 4.

Der er 2 typer callback der kan udføres. Frontside og serverside.

Frontside callback er selve navigeringen af kunden tilbage til bestil step 4. Denne navigering vil afslutte ordren og markere den som gennemført i shop admin. Siden kunden kun har navigeret væk fra shoppen og tilbage igen i samme browser, så genkender shoppen stadig kundesessionen. Frontside callback skal altid foretages, da det er brugerens mulighed for at se at transaktionen er gået godt. Men fordi det er en browser navigation er der forhøjet risiko for at den bliver afbrudt af klienten (mistet internet, for hurtigt lukket vindue). Du kan derfor ikke være helt sikker på at et manglende frontside callback betyder at betalingen er fejlet.

Derfor er serverside callback en mulighed. Det er valgfrit, men tilrådeligt at lave et serverside callback til shoppen for at cleare betalingen før og uafhængigt af frontend navigeringen af kunden. Fordi en shop sagtens kan være i gang med at gennemføre en lang række ordrer på samme tid, så kræver dette at man samtidig sender en session med i server callback som en request header (“Cookie”). På den måde kan shoppen genkende ordren og afslutte den korrekt.

Checksum

Det er valgfrit, men tilrådelig, at benytte checksum ved integrationen. Der er mulighed for en udgående (fra shoppen) checksum og en separat tilbagegående checksum. Ved brug af checksum forhindrer du at 3. part kan opsnappe kaldet og f.eks. ændre beløbet. Eller sende et callback tilbage til shoppen uden at betalingen er gennemført.

Checksummen er lavet med en md5 kryptering af en unik streng. Stengen er sammensat at 4 parametre:

Ordrenummeret + Beløbet + En hemmelig nøgle + Valuta koden

Som eksempel kan vi forestille os en kald hvor ordrenummeret er 2000, hvor beløbet er 500kr i dansk valuta, som har valutakode 208 (Valutakoder følger ISO 4217 ). Vi har samtidigt defineret en hemmelig nøgle “sesamlukdigop”. Den sammensatte streng er derfor

“2000+500,00+sesamlukdigop+208”

Bemærk her at plus + tegnene faktisk er en del af strengen og ikke kun illustrative.

Hvis man nu laver en MD5 kryptering af strengen får man i stedet denne streng:

“CE88E1E72A9A945D4D7811E73A6AF9B6”

Og det er denne der skal valideres. Shoppen leverer checksummen, ordrenummeret, beløb og valutakoden for en transaktion. Men den hemmelige nøgle leveres ikke. Det er den ubekendte. Men hvis dit eget system kender denne, kan du regne checksummen ud og sammenligne med den modtagede checksum. Og hvis de ikke matcher, så ved du at du ikke kan stole på at f.eks. beløbet ikke er blevet ændret undervejs og du bør afbryde transaktionen.

Forskellige scriptsprog har forskellige måder at håndtere MD5 kryptering. I PHP er det f.eks. en indbygget funktion, mens ASP kræver en ekstra komponent. Det er op til dig selv hvordan du vil arbejde med MD5; der findes mange kilder til det på nettet. Prøv f.eks. at søge på nettet efter “online md5” og så vil du finde mindst 10 forskellige online tools til at kryptere en streng med MD5 krypterings algoritmen. Dette er hjælpsomt, når du skal sidde og teste funktionen efter.

Når du skal sende et callback tilbage til shoppen kan du også dér vælge at sende en MD5 krypteret checksum med. Shoppen vil så kun acceptere kaldet hvis denne stemmer overens med dens forventning. Bemærk at du på betalingsmetoden i shoppen skal definere 2 forskellige nøgler til henholdsvis hovedkaldet (“API key”) og callback (“API complete order key”). Det er nødvendigt med en separat nøgle, da man ellers kunne fuppe shoppen til at markere en ordre som betalt ved bare at returnere den samme checksum.

Bemærk! Checksum til callback er lidt anderledes end den første checksum, da den ikke gør brug af beløbet. Den hedder altså i stedet:

Ordrenummeret + En hemmelig nøgle + Valuta koden

Det er meget sandsynligt at vi på et tidspunkt ændrer dette, så alle 4 elementer også bruges i kaldet tilbage for at ensarte det. Så forbered din kode på begge dele, så du nemt kan skifte over.

Vigtigt om total beløbet

Shoppen sender totalbeløbet (se herunder) formateret som det er formateret i shoppen. En amerikansk shop ville f.eks. have ombyttet tusindstals seperatoren og skrive 2,345.75 i stedet for 2.345,75 som der ville stå i en dansk shop. Det er meget vigtigt når du sammensætter MD5 strengen at du konverterer beløbet til en streng der IKKE har en tusindtals separator og som bruger komma som decimal separator. Altså 2345,75 i dette tilfælde. For ellers bliver strengen og dermed checksummen forkert.

Flowchart

Her kan du se et flowchart over best practice for kommunikation mellem shoppen og dit script med brug af checksum.

BetalingsAPI Flowchart

Request variabler

Herunder er der en oversigt over de request variabler som du kan trække ud til brug af dit script.

For at tilgå variablerne i dit script, skal du i klassisk ASP trække dem ud som:

Eller i PHP skal du i stedet bruge denne form:

Ud over de variabler du skal bruge til selve transaktionen (beløb mm.) er deres også variabler der omhandler kunde data, leverings adresse og endda mulighed for at hente de enkelte ordrelinjer. Det er op til dig selv hvor mange af variablerne du vil bruge til noget. Mange af dem vil ikke have nogen relevans for din implementation og er kun med for at give dig valgmuligheder.

De sidste 5 variabler omhandler en specifik ordrelinje og bliver gentaget for hver ekstra ordrelinje ordren består af. Hvis du vil løbe dem alle igennem skal du bruge en while konstruktion, da der er et ukendt antal ordrelinjer og så afbryde når variablenavnX ikke eksisterer.

Alle data leveres som en tekst streng.

Request varabel	Notat
APIkey	Dette er den MD5 krypterede streng du skal validere som checksum.
APIMerchant	Et forretnings nummer der evt. skal bruges i integrationen. Indtastes på betalingsmetoden.
APIOrderID	Ordrenummeret (Et af elementerne til checksum).
APISessionID	En unik streng som skal sendes tilbage med serverside callback for genkendelse af shoppen.
APISharedSessionID	Indeholder et unikt id som skal sendes med i callback til order4.html. ID’et skal sendes via URL parameteren &sharedsessoinid=”id”
APICurrencySymbol	Valutaens betegnelse valgt i shoppen som streng. F.eks. “DKK” eller “£”.
APITotalAmount	Det totale beløb der skal betales. Bemærk at det modtages med samme decimal og tusindtalsseperator som shoppen er sat op til at bruge. Så en amerikansk shop kunne skrive “2,145.50” hvor en dansk ville skrive “2.145,50”. (Et af elementerne til checksum; se “Vigtigt om totalbeløbet” længere oppe).
APICallBackUrl	Denne indeholder typisk URL’en til shoppen forside. Den bruges hvis kunden skal ledes til shoppen i en sammenhæng der ikke direkte er relateret til afslutningen af transaktionen. F.eks. ved noget efterbehandling.
APIFullCallBackOKUrl	Dette er den URL du skal lade kunden navigere via for at vendet tilbage til bestil step 4 af shoppens ordreflow. Den inkluderer en variabel omkring shoppens design, så shoppen ved hvilket design den skal loade. Det er ikke så vigtigt; det vigtige er at vide at når kunden kommer tilbage til shoppen via denne URL, så afsluttes ordren i shoppen samtidigt. En evt checksum kan tilføjes med parameteren: &PayApiCompleteOrderChecksum=xxx
APICallBackOKUrl	Denne variabel er ikke længere i brug.
APICallBackServerUrl	Dette er den URL du kan lave et severside kald til for at sætte transaktionen som gennemført i shoppen uafhængigt af kundens navigering. Kaldet skal indeholde SessionID variablen som en Request header (“Cookie”) for at shoppen kan genkende den rigtige session, den skal afslutte. En evt checksum kan tilføjes med parameteren: &PayApiCompleteOrderChecksum=xxx
APILanguageID	Dette angiver ID på det site ordren er blevet gennemført på hvis shoppen arbejder med flere sites. F.eks. kunne “26” betyde et danskt site og “27” et engelsk site, så derved ved du om du skal tilpasse noget tekst på din side heraf.
APITestMode	Betalings metoden i shop Admin giver mulighed for at angive om metoden pt skal køre “live” eller “test”. Du kan bruge dette i din implementering hvis der skal kunne laves test af dit script. F.eks. kunne du give mulighed for at dit script kan simulere en betaling før shopejer reelt har oprettet en aftale med 3. part og der derfor måske ikke findes et forretningsnummer endnu. Reelt er det her bare en boolsk variabel, så du kunne også bruge den til et hvilket som helst formål du kunne finde på hvor shopejer i driftperioden skal kunne toggle på et eller andet i dit script.
APIPayGatewayCurrCode	Dette er valutakoden. Den følger ISO 4217 standarden, hvor 208 f.eks. betyder DKK. I shop admin definerer man valutakoden for et givet leveringsland. (Et af elementerne til checksum).
APICardTypeID	Dette er en liste af tilladte korttyper som kan defineres på betalingsmetoden i shop admin. For de fleste integrationer er dette en ligegyldig variabel, da det slet ikke er sikkert at din betalingsmetode har noget med kreditkort at gøre. Listen af korttyper hænger sammen med DanDomains eget betalingssystem og de korttyper der tilbydes der. Ideen er at man kan have flere betalingsmetoder for at håndtere forskellige korttyper med forskellige gebyrer, så f.eks Dankort og Mastercard ikke håndteres på samme måde. Cardtype ID 0 betyder “alle valgt” mens individuelle valg vil komme som en liste “1,4” betyder f.eks. Dankort (1) og Visa/Dankort (2). For den opfindsomme integrator giver denne variabel en hel række indstillingsmuligheder for integrationen, da du reelt kan bruge oplysningen om at der er sat kryds i “Dankort” (1) til hvad som helst. Det kan nok virke mærkeligt for shopejer at skulle “sætte kryds ved Mastercard hvis du ønsker en blå baggrund på betalingssiden”, men det ER dog noget der giver dig muligheder for tilpasning af dit script.
APICRekvNr	Kundedata primær adresse – Et evt. rekvisitions nummer.
APICName	Kundedata primær adresse – Kundens navn. For virksomhed er dette typisk kontaktperson.
APICCompany	Kundedata primær adresse – Et evt virksomheds navn for en virksomhed.
APICAddress	Kundedata primær adresse – Adresse 1 feltet.
APICAddress2	Kundedata primær adresse – Adresse 2 feltet .
APICZipCode	Kundedata primær adresse – Postnummer.
APICCity	Kundedata primær adresse – By.
APICCountryID	Kundedata primær adresse – Dette er det interne ID shoppen bruger for et givet leveringsland. Det er et unikt ID for hvert site i shoppen, så “Danmark” på 2 forskellige sites vil have 2 forskellige ID. Der er nok ikke meget at bruge dette ID til i implementations sammenhæng, men hvis du vil vedlige holde en landeliste i din ende af en eller anden grund kan du matche det om med disse. Typisk hvis data også skal videre til et økonomisystem.
APICCountry	Kundedata primær adresse – Landenavn.
APICPhone	Kundedata primær adresse – Telefonnummer.
APICFax	Kundedata primær adresse – Fax nummer.
APICEmail	Kundedata primær adresse – E-mail adresse. Ordrebekræftelse vil typisk blive sendt til denne.
APICNote	Kundedata primær adresse – Kundenotat. Beregnet til meddelelse fra kunde til shopejer.
APICcvrnr	Kundedata primær adresse – Cvr nummer, hvis kunden er en virksomhed.
APICCustTypeID	Kundedata primær adresse – Angiver kundetype: 0 = Privat, 1 = Virksomhed, 2 = Offentlig.
APICNumber	Kundens kundenummer
APICEAN	Kundedata primær adresse – EAN nummer, hvis kunden er en offentlig instans.
APICres1	Kundedata primær adresse – Reserveret felt 1; shopejer kan definere dette til hvad som helst.
APICres2	Kundedata primær adresse – Reserveret felt 2; shopejer kan definere dette til hvad som helst.
APICres3	Kundedata primær adresse – Reserveret felt 3; shopejer kan definere dette til hvad som helst.
APICres4	Kundedata primær adresse – Reserveret felt 4; shopejer kan definere dette til hvad som helst.
APICres5	Kundedata primær adresse – Reserveret felt 5; shopejer kan definere dette til hvad som helst.
APIDName	Kundedata alternativ adresse – Kundens navn. For virksomhed er dette typisk kontaktperson.
APIDCompany	Kundedata alternativ adresse – Et evt virksomheds navn for en virksomhed.
APIDAddress	Kundedata alternativ adresse – Adresse 1 feltet.
APIDAddress2	Kundedata alternativ adresse – Adresse 2 feltet.
APIDZipCode	Kundedata alternativ adresse – Postnummer.
APIDCity	Kundedata alternativ adresse – By.
APIDCountryID	Kundedata alternativ adresse – Dette er det interne ID shoppen bruger for et givet leveringsland. Det er et unikt ID for hvert site i shoppen, så “Danmark” på 2 forskellige sites vil have 2 forskellige ID. Der er nok ikke meget at bruge dette ID til i implementations sammenhæng, men hvis du vil vedlige holde en landeliste i din ende af en eller anden grund kan du matche det om med disse. Typisk hvis data også skal videre til et økonomisystem.
APIDCountry	Kundedata alternativ adresse – Landenavn.
APIDPhone	Kundedata alternativ adresse – Telefonnummer.
APIDFax	Kundedata alternativ adresse – Fax nummer (sjældent brugt).
APIDEmail	Kundedata alternativ adresse – E-mail adresse.
APIDean	Kundedata alternativ adresse – EAN nummer, hvis kunden er en offentlig instans (sjældent brugt).
APIShippingMethod	Navnet på den valgte forsendelsesmetode.
APIShippingMethodId	ID’et på den valgte forsendelsesmetode
APIShippingFee	Forsendelses gebyrets størrelse (fragt).
APIPayMethod	Navnet på den valgte betalingsmetode.
APIPayMethodId	ID’et på den valgte betalingsmetode
APIPayFee	Betalings gebyrets størrelse.
APICIP	Kundens IP adresse.
APIBasketProdNumber1	Produktnummer på den første ordrelinje.
APIBasketProdName1	Produkt navn på den første ordrelinje.
APIBasketProdAmount1	Antal på den første ordrelinje.
APIBasketProdPrice1	Prisen på den første ordrelinje inklusiv moms.
APIBasketProdVAT1	Momssatsen på den første ordrelinje. F.eks. “25” ved en dansk momssats på 25%. Altså IKKE momsbeløbet.

Opsætning af en betalingsmetode der benytter Betalings API

Indstillinger –> Betaling

En betalingsmetode der bruger Betalings API’et fungerer grundlæggende som andre betalingsmetoder i shoppen. Dem læser du nærmere om under Betalingsmetoder.

For at sætte en betalingsmetode op til at bruge Betalings API, skal du først oprette selve betalingsmetoden. Navngivning, logo og evt. betalingsgebyr fungerer som ved andre betalingsmetoder. Det der adskiller en betalingsmetode, der skal benytte betalings API, er at du skal vælge den betalingsløsning der hedder “Betalings API” (Se billede herunder). Hvis du ikke har muligheden, så er det fordi du ikke har abonnement på appen og du er nødt til at tilkøbe denne først igennem webshoppens appstore.

Når du vælger betalingsløsningen “Betalings API” får du adgang til en række underpunkter. Herunder kan du se hvordan disse ser ud og i tabellen længere nede er felterne forklaret.

Felt	Note
Vælg betalingsløsning	Her vælges Betalings API blandt andre betalingsløsninger. Bemærk at Betalings API er et tilkøb til shoppen og derfor kun dukker op hvis du har det med i dit abonnement.
Forretningsnummer	Her skriver du et evt. forretningsnummer til din dit eksterne system. Indholdet sendes med i request variablen “APIMerchant”.
API URL	Her tastes URL’en til det script der skal kaldes når en ordre i shoppen bliver gennemført med denne betalingsmetode. Typisk vil scriptet ligge et eksternt sted, hvorved den komplette sti til scriptet skal indtastes.
API Key	Her tastes en evt. tildelt nøgle / checksum key. vi anbefaler at man benytter sig af både ”API Key” og ”API complete order key” for at undgå svindel.
API complete order key	Her tastes en evt. tildelt nøgle / checksum key. vi anbefaler at man benytter sig af både ”API Key” og ”API complete order key” for at undgå svindel.
Status	Sættes altid til “Live” ved brug af Betalings API
Tilladte korttyper	Her skal “Alle” altid markeres ved brug af Betalings API