Hvordan kan vi hjælpe dig?

Velkommen til OnlineFundraisings supportunivers, hvor du finder hjælp og vejledning i vores artikler og videoer. Tag et kig rundt eller brug søgefunktionen nedenfor. Du er altid velkommen til at tage kontakt til vores support, hvis du har et spørgsmål, du ikke kan finde svaret på.

Payment Session Handler API

Introduktion til Payment Session Handler

Senest redigeret:

Artiklerne i denne sektion skal læses som inspiration til integration med vores Payment Session Handler (PSH) i egen applikation, og er i høj grad et supplement til vores API dokumentation.

Indhold i denne sektion:

  • Anbefalet praksis
    • Benyt DataSet
    • Oplys Contact. Opret ikke selv.
    • Definér Communication
    • Definér Purpose Accounting Code
    • Benyt initialUserRedirectUrl
  • Gateways og betingelser
    • Betalingskort (Card)
    • MobilePay Subscriptions
    • Betalingsservice
      • Frister
    • SMS
  • Forslag til validering
    • Data og felttyper
    • Validering og udfyldelse af adresse
    • Validering og udfyldelse af by ved postnr.
    • Validering og udfyldelse af navn og adresse ved tlf.nr.
    • Validering af CPR-nr. med modulus 11
    • Validering og udfyldelse af firmanavn og adresse ved CVR-nr.
    • Verifikation om brugen af BS App ved CPR-nr.
  • Payment Session Handler API

 

 

Er du usikker på hvilke gateways organisationen benytter, samt hvordan de hver især er konfigureret, kontakt da venligst OnlineFundraising på support@onlinefundraising.dk, gerne med kontaktpersonen hos organisationen sat cc i e-mailen.

 

Anbefalet praksis

Vores API er åben og der kan findes argumenter for at benytte den anderledes end vi selv gør i såvel formularer som telemarketing-løsninger, men vi anbefaler følgende aspekter tages i betragtning i din applikation og dennes integration med vores PSH.

Benyt DataSet

Da vores Payment Engine API udelukkende har et transaktionelt sigte, og ikke må forveksles med et CRM, efterlader vi ikke rum for valgfri metadata hér, selvom de enkelte datapunkter kan have stor forretningsmæssig værdi for den enkelte organisation.

Til gengæld tilbyder vi med vores DataSet API at applikationer kan tilknytte et valgfrit antal datapunkter til den enkelte betalingssession, således at øvrige integratorer, såsom CRM, stadig har mulighed for at sammenholde betalingssessionens transaktionelle forhold med øvrig relevant metadata. Eksempler på disse tæller UTM-parametre m.v. relevant for fundraiseren.

Bemærk at PSH tilfører det definerede DataSet relevante transaktionelle guids umiddelbart efter en succesfuldt gennemført betalingssession. Dermed er DataSet også et godt øjebliksbillede af hvad der faktuelt blev oprettet, skulle der evt. senere opstå usikkerhed ifm. flere integratorers anvendelse af vores API.

Se venligst vores API dokumentation for DataSet der udtrykker vores anbefaling til strukturen.

Oplys Contact. Opret ikke selv.

Selvom vores API understøtter evnen til at oprette Contacts, anbefaler vi ikke at gøre brug af dette, men i stedet medsende oplysningerne på Contact i kaldet til PSH.

Dette anbefaler vi med afsæt i, at vi kun ønsker at opbevare personfølsomme oplysninger hvor der findes et transaktionelt grundlag. Dette betyder samtidig at vi kun opretter en Contact ved en succesfuld gennemført betalingssession.

Skulle man være interesseret i indblik i hvem og hvor mange der har startet en betalingssession, men ikke gennemført, henviser vi til DataSet.

Definér Communication

Din applikation kan med fordel benytte sig af vores Communication API til håndtering af bekræftelser, og evt. senere behov for påmindelser ved forskellige hændelser. Hvad der kommunikeres ved hver hændelse, afgør den enkelte Communication Collection, samt om det i visse tilfælde skal undlades at kommunikere.

Derudover er det nødvendigt for Betalingsservice at en Communication Collection defineres i kaldet til PSH, da denne afgør hvilken tekst der skal påføres den enkelte opkrævning. Alternativet er, at teksten kun indeholder organisationens navn, uden evne til senere at påvirke den.

Se evt. vores hjælpeartikel til organisationens brug af Communication.

Definér Purpose Accounting Code

Som hjælp til bogføring af de indsamlede midler tilbyder vi to typer af bogføringskoder:

  1. Payment Method Accounting Code, påført entiteterne Payment og Payment Method.

    Disse beror på en fastdefineret liste af koder, som fortæller bogholderen hvordan udbetalingen vil finde sted idet hver gateway og dennes tilvalgsmuligheder håndterer udbetaling forskelligt. Dette er, til orientering, ikke noget OnlineFundraising har indflydelse på.

  2. Purpose Accounting Code, påført entiteterne Payment og Agreement.

    Disse bør defineres af organisationen, da de fortæller bogholderen hvor midlerne skal kanaliseres hen. Tilsammen letter de bogholderens arbejdsgang.

    Til orientering påføres Purpose Accounting Code på Agreement de senere affødte Recurring Payments.

Det er også værd at bemærke visse CRM integrationer benytter Purpose Accounting Code til at identificere om indbetalingen eller betalingsaftalen vedrører et produkter, et medlemskab eller andet.

Benyt initialUserRedirectUrl

Ved kald til PSH returneres flere URL’er, heriblandt vores såkaldte “preWait” og “postWait”. Her anbefaler vi udelukkende at benytte og dermed videresende til: “initialUserRedirectUrl”, da dette automatisk fører donorer igennem betalingssessionens faser og tilslut den medsendte: “successReturnPageUrl” eller “errorReturnPageUrl”.

Til orientering er “preWait” og “postWait” to ventepositioner hvor donor hhv. venter på at valgte betalingsgateway er klar, og betalingsgateway efterfølgende har givet positiv konfirmation af udfaldet. Dette gør det muligt for os at placere donorer i kø ved evt. spidsbelastning hos os selv eller den valgte betalingsgateway.

En applikation kunne godt vælge at håndtere disse ventepositioner skjult, eller erstatte dem med egen brandet håndtering, men den anbefalede rute til hurtigt at komme igang er at undlade dette.

 

 

Gateways og betingelser

Hver gateway opererer forskelligt for såvel opkrævning og udbetaling som oprettelse, hvorfor det er nødvendigt din applikation forholder sig derefter.

Betalingskort (Card)

Understøtter både faste aftaler evt. suppleret med straksbetaling (OneOff), på samme eller andet beløb, og enkeltvise betalinger.

Obligatorisk er kortoplysningerne.

Bemærk at PSH kun understøtter “instant capture”, og dermed ikke giver mulighed for reservering af beløb.

MobilePay Subscriptions

Understøtter faste aftaler med straksbetaling (OneOff), på samme eller andet beløb.

Obligatorisk er tlf.nr.

Bemærk at første mulige opkrævning påvirkes af, om man d.d. har passeret MobilePay Subscriptions’ frist for advisering. Fristens varighed kan konfigureres fra organisation til organisation, men er som minimum én dag. Skulle man dog oprette en fast aftale f.eks. tre dage efter en adviseringsfrist på syv dage, da vil vores Payment Engine automatisk opkræve første gang med en forskydelse på fire dage.

Betalingsservice

Understøtter kun faste aftaler via oplysning af CPR-nr. eller CVR-nr., og så enten reg.nr. og kontonr. eller via BS App.

Dertil stilles der krav til navn eller firmanavn, samt adresse, såfremt man er hhv. privatperson eller firma, og organisationen benytter Betalingsservices Totalløsning, der understøtter udsendelse af FI-kort (også kendt som girokort).

Se venligst afsnittet for anbefalet praksis omkring Communication ovenfor.

Bemærk at første mulige opkrævning afhænger af, om man d.d. har passeret Betalingsservices frist for aflevering af en BS 601-fil, samt om det inden da er muligt at bekræfte oprettelsen. Ved oprettelse med CPR-nr. eller CVR-nr., samt reg.nr. og kontonr., kræves yderligere 24 timer førend bekræftelsen modtages, hvorimod oprettelse med BS App bekræftes straks. Dette er med udgangspunkt i at OnlineFundraising er organisationens dataleverandør, hvor man i modsat fald også skal indregne dataleverandørens processeringstid.

Frister

Vælger man at vejlede donor ift. hvornår første opkrævning finder sted, bør man derfor forholde sig til de givne frister, samt metoden for oprettelse.

Vi kan anbefale, at man evt. benytter eller lader sig vejlede af den tilgang, som OnlineFundraising benytter. Ud fra de offentliggjorte Betalingsservice frister opretter vi en række JSON specifikationsfiler for hvert måned.

Disse er frit tilgængelige og kan findes her:

https://info.onlinefundraising.dk/bs/bs_{year}_{month}.json

Bemærk, at du skal angive år og måned for at tilgå specifikationsfilen for én bestemt måned. Årstal angives som 4 cifre, og måned som 2 cifre. For at tilgå BS specifikationsfilen for juli-måned 2021 ville URL’en derfor være: https://info.onlinefundraising.dk/bs/bs_2021_07.json

Betalingsservice udgiver halvårligt sine frister her.

SMS

Kan aktuelt ikke oprettes vha. PSH.

Forslag til validering

Hver applikation har sine egne ambitioner og begrænsninger, samt sin egen brugergruppe for øje. Følgende er en ikke-udtømmende liste af valideringer vi selv benytter i vores formularer som kan være til inspiration.

Data og felttyper

Foruden de krav vi stiller til transaktionelle oplysninger finder vi selv hjælp i følgende sammenhæng mellem datapunkter og felttyper.

Datapunkt

Felttype

Validering

CPR-nr.

tel

10 cifre

CVR-nr.

tel

8 cifre

Tlf.nr.

tel

8-20 cifre, påført landekode (f.eks. 45 for DK)

Email

email

Valid email-adresse

Navn og lign.

text

Tillad ikke specialtegn og cifre

Adresse

text

Supplér evt. med DAWA-validering

Postnr.

text

Aht. udenlandsk

By

text

Tillad ikke specialtegn og cifre

Land

select

Benyt landekoder

Bemærk at vores PSH ikke selv samler “name” på baggrund af “firstName” og “lastName”, og ej heller opdeler på baggrund af “name”, hvorfor vi anbefaler definition af navn via adskilte felter for for- og efternavn.

Validering og udfyldelse af adresse

Hjælp gerne brugeren med at udfylde sin adresse ved dynamisk opslag i DAWA, hvilket samtidig sikrer ensartet formatering af adresserne. Overvej desuden om adressens guid hos DAWA skal medsendes.

Bemærk at DAWA kun rummer adresser i Danmark, hvilket ikke indbefatter Grønland og Færøerne. I de tilfælde kan validering f.eks. foregå ved Google Maps API.

Se API dokumentation for DAWA, samt Google Maps.

Validering og udfyldelse af by ved postnr.

Hjælp gerne brugeren med at udfylde by på baggrund af et givent postnr.

Se links til API dokumentationer ovenfor.

Validering og udfyldelse af navn og adresse ved tlf.nr.

Hjælp gerne brugeren udfylde sit navn og adresse ved offentligt tilgængelige oplysninger tilknyttet et givent tlf.nr. Dette kan evt. fungere i samspil med DAWA-validering af adressen, da syntaksen kan afvige, ligesom DAWA’s tilsvarende guid kan være ønsket.

En tjeneste som dette blev tidligere understøttet af Eniro, hvorfor alternativer skal findes særskilt.

Validering af CPR-nr. med modulus 11

Hjælp gerne brugeren med at oplyse korrekt CPR-nr. til skattefradrag og/eller Betalingsservice ved modulus 11 validering.

Husk at tage højde for datoer uden modulus 11 kontrol.

Validering og udfyldelse af firmanavn og adresse ved CVR-nr.

Hjælp gerne brugeren med at udfylde firmanavn og adresse i kraft af CVR-registret. Dette kan evt. fungere i samspil med DAWA-validering af adressen, da syntaksen kan afvige, ligesom DAWA’s tilsvarende guid kan være ønsket.

Se API dokumentation for CVR API.

Verifikation om brugen af BS App ved CPR-nr.

Hjælp gerne brugeren ved kun at afkræve de nødvendige oplysninger for den valgte gateway, så der f.eks. kun afkræves reg.- og kontonr. ifm. Betalingsservice, hvor det er uvist hvorvidt brugeren har BS App.

Dette kan dog kun lade sig gøre, hvis OnlineFundraising er dataleverandør for organisationen. I dét tilfælde, kontakt da venligst OnlineFundraising for at høre nærmere om mulighederne.

Var denne artikel en hjælp?

0 ud af 0 fandt dette nyttigt

Relaterede artikler