PayApi / efterbehandling af transaktioner

Med PayApi kan man undgå login til https://pay.dandomain.dk administrationen, når man skal hæve mv. i sit betalingssystem. Det vil sige, at man kan hæve en transaktion ved et enkelt http kald. Det kan indbygges i eks. ERP systemer, Intranet eller andet.

URL’en til at lave et kald til webservicen: https://pay.dandomain.dk/PayApi.asp?username=yyyyyyy&password=xxxxxxx

(yyyyyyy og xxxxxxxx ændres til hhv. brugernavn og password der benyttes til at logge ind i betalingssystem administrationen)

Eksempel:

https://pay.dandomain.dk/PayApi.asp?username=yyyyyyy&password=xxxxxxx&capture=1&orderid=1020

Her hæves en eksisterende transaktion med ordre id 1020, hvis capture er sat til værdien 1.

Der kan tilføjes yderligere parametre, hvis der ønskes udført andre funktioner sammen med hævning af beløbet.

Eksempelvis en nedjustering af beløbet der hæves:

https://pay.dandomain.dk/PayApi.asp?username=yyyyyyy&password=xxxxxxx&capture=1&orderid=1020&ChangeAmount=1&Amount=22

Parameter Beskrivelse
Username (krævet) Forretningens merchantnummer tildelt af PBS
Password (krævet) Password som bruges til log ind i betalingssystemet
Capture (krævet) Skal være 1 for at hæve
Orderid OrdreID på den transaktion der skal hæves.

(valgfri – men krævet hvis TransID ikke er udfyldt)

Transid Transaktions ID på den transaktion der skal hæves.

(valgfri – men krævet hvis OrdreID ikke er udfyldt)

DoAmountCheck (Valgfri) Hvis sat til 1 vil der valideres om beløb på transaktionen stemmer overens med det angivet i amount parametren.
ChangeAmount (Valgfri) Hvis sat til 1 vil beløbet på transaktionen blive ændret til det angivet i amount parametren.

Bemærk! DoAmountCheck må ikke være udfyldt og amount må ikke være større end det original beløb der findes på transaktionen.

Amount (Valgfri) Skal udfyldes med beløbet, hvis DoAmountCheck eller ChangeAmount sættes til
Partialcapture Hvis sat til 1 foretages der en delhævning. Kræver at Amount og Transid medsendes samt, at der er benyttetSupplementary Authorisation.
Partialcredit Bruges til at kreditere en delhævning. Kræver medsendelse af Amount, og parameteren PartialCaptureID. PartialCaptureID er det transaktionsnummer den delhævede transaktion tildeles.

Statuskoder

Der er muligt at få vist statuskoder. Disse er for de enkelte kald (Capture, Renew, Reject) defineret således:

Parameter Beskrivelse Format
Capture=1

 

eller

 

Partialcapture=1


ShowStatusCodes=1

Hæver transaktioner ud fra OrderID


406 – Amount mismatch

405 – Amount parameter invalid

409 – Amount cannot exceed original amount

404 – Transaction not found

407 – Transaction #XXXXXXX is expired. (Should be renewed)

Case 0 = 200 – Transaction # & TransID & successfully captured.  Amount

Case 1 = 402 – Transaction #” & TransID & ” could not be captured”

Case else =  403 – Invalid transaction

Generel fejlkode: 404 – FEJL! Det er i øjeblikket ikke muligt at hæve transaktionen – da PBS har problemer. Forsøg venligst senere…<br>

Int
Renew=1


ShowStatusCodes=1

Muliggør fornyelse af transaktioner der er udløbet


200 – Transaction # “number” successfully renewed.

404 – Transaction error.

Ellers udskrives:

404 – Transaction not found.

Int
Reject=1


ShowStatusCodes=1

Muliggør afvisninger af transaktioner


200 – Transaction # “number” successfully rejected.

404 – Transaction # “number” not found.”

ellers udskrives:

404 – Transaction not found

Int
Credit=1


ShowStatusCodes=1

Giver mulighed for at kreditere en ordre. “Amount” kan sendes med hvis man kun ønsker at kreditere en del af ordren. Sendes denne ikke med krediteres det fulde beløb.


200 – Transaction # “number” successfully credited.

404 – Transaction error.

Ellers udskrives:

404 – Transaction not found.

Int

 

Download eksempel

Eksempelfil Beskrivelse

Download

remote_handler.txt Filen indeholder mulighed for, via nogen få ændringer i variabler for eksempelvis brugernavn og password mv. at udføre fjern behandling af transaktioner. Funktionerne er fornyelser, afvisninger og hævning af transaktioner.

Download

 

Kontrol af transaktioners status

Eksempel: https://pay.dandomain.dk/PayApi.asp?username=yyyyyyy&password=xxxxxxx&Checkstatus=1&OrderID=2365

Parameter Beskrivelse Format
Checkstatus (1)

 

Udskriver status for transaktioner ud fra OrderID


200 – Transaction #123 exists. Not captured. OrderID:2365; Amount:100; OrigAmount:100

201 – Transaction #123 exists. Captured. OrderID:2365; Amount:100; OrigAmount:100

202 – Transaction #123 exists. Rejected. OrderID:2365; Amount:100; OrigAmount:100

203 – Transaction #123 exists. Credited. OrderID:2365; Amount:100; OrigAmount:100

404 – Transaction not found

Int

 

Download eksempel

Eksempelfil Beskrivelse

Download

remote_statuscheck.txt Filen indeholder mulighed for, via nogen få ændringer, at få vist status for transaktioner via fjernkald af denne fil.

Download

 

Specielt for abonnementsbetalinger (kræver specialaftale med Nets!)

Der gælder specielle parametre til https://pay.dandomain.dk/PayApi.asp. Udgangspunktet er dog stadigt:

https://pay.dandomain.dk/PayApi.asp?username=yyyyyyy&password=xxxxxxx

når der forsøges at ændre eller kalde eksisterende abonnementer.

Nedenstående benyttes til at oprette, rette og hæve via eksterne sider, som intranet, ERP / økonomisystemer, extranet, mv.

Parameter Beskrivelse Format
PreAutRecurring

(Funktionskald)

 

Angiver at en betaling skal oprettes som en abonnementsbetaling. En “Pre Authorization”, altså en præ kontrol, ved PBS, som muliggør tjek for om der kan foretages abonnements betalinger på kortet.


Status koder:

200 – Subscribtion #123 successfull Pre-aut

201 – Subscribtion #123 successfull Pre-aut Update

402 – Subscribtion #123 Pre-aut Failed

403 – Subscribtion #123 Pre-aut Failed – Customer number already exists

404 – Subscribtion #123 Pre-aut Failed – Max recurring limit reached


Ved tilføjelse af UpdateExistingSubscriber til PreAutRecurring, gives status koden:

201 – Subscribtion #123 successfull Pre-aut Update

Int
PreAutInstantCapture

(Funktionskald)

Foretager gen-autorisation ved PBS, og danner efterfølgende capture ved PBS for at hæve beløbet / starte første abonnementsbetaling. Int
RecurringCustNumber

(Variabel)

Værdien af kundenummer indsættes på abonnementet. Denne tager både tal og bogstaver som værdi. Værdi krævet hvis der udføres RecurringCapture, altså hævning af beløbet på vedkommende abonnement. String
RecurringDays

(Variabel)

Sætter intervallet af dage mellem hver betaling på abonnementet. Int
RecurringMonths

(Variabel)

Sætter intervallet af månder mellem hver betaling på abonnementet. Int
RecurringAmount

(Variabel)

Sætter beløbet der skal tillægges abonnementsbetalingen. Krævet hvis funktionen PreAutInstantCapture benyttes. Money
RecurringCurrency

(Variabel)

Sætter CurrencyID der bruges for abonnementsbetalingen. Currency ISO
RecurringNextCapture

(Variabel)

Angiver en dato for hvornår den næste abonnementsbetaling skal finde sted.

 

Date
PreAutCardNumber

(Variabel)

Kreditkort nummer.

 

Int
PreAutCardCVC

(Variabel)

Kreditkort kontrolcifre.

 

Int
PreAutCardExpireYear

(Variabel)

Kreditkort udløbs år.

 

Int
PreAutCardExpireMonth

(Variabel)

Kreditkort udløbs måned.

 

Int
RecurringCapture

(Funktionskald)

 

Giver mulighed for at foretage hævning af beløb på et angivet abonnement. Hvis RecurringAmount er angivet, foretages der hævning på dette beløb, ellers hentes beløbet fra abonnementets faste beløb. Altså, hvis RecurringCapture er sat til værdien 1, og evt. RecurringAmount er ændret i forhold til original beløbet, vil man kunne justere beløbet for det enkelte abonnement.

Status koder:

200 – Customer #[kundenummer] successfully captured (xxx,xx) on transaction [TransID]

402 – Customer #[kundenummer] Capture Failed

1
RecurringDelete

(Funktionskald)

Opdatering og deaktivering af abonnementer kan udføres ved at sende en parameter: RecurringDelete til payapi.asp. Denne vil give følgende status koder tilbage når den udføres:

200 successfully deleted

402 delete Failed – Customer not found

403 delete Failed – Customer already deleted

RecurringStatusList

(Funktionskald)

 

Giver mulighed for at hente en liste over abonnementer ud fra følgende søgekriterier:

1 – for abonnementer der skal hæves idag.

2 – for abonnementer der skulle have været hævet.

3 – for abonnementer hvor kortet er udløbet.

Denne kan køres selvstændig, eksempelvis således:

https://pay.dandomain.dk/payapi.asp?Username=xxxxxxx&Password=yyyyyyyy&RecurringStatusList=1

eksemplet vil så vise, i dette tilfælde med status listen 1, en liste over alle abonnementer.

1 / 2 / 3
UpdateExistingSubscriber

(Variabel)

Giver mulighed for opdatering af et eksisterende abonnement. Ved en opdatering SKAL alle normale parametre til en abonnements-oprettelse medsendes. Det betyder altså at kunden vil skulle det normale “betalings-flow” igennem igen. Men ved at sende UpdateExistingSubscriber=1 med, vil der i stedet for oprettelse af et nyt abonnement rettes i et eksisterende.

Grunden til at kunden skal igennem et nyt “betalings-flow” er at Nets kræver en gensendelse af alle kort data for at kunne ændre beløbet.

Forklaret i tekst, vil: <input type=”hidden” name=”UpdateExistingSubscriber” value=”1″> tilføjet i det normale “betalings-flow” medføre at:

– PreAuthTicket

– ClientIP

– CardType

– PreAuthExpirationDate

– RecurringCurrencyID

– RecurringAmount

altid opdateres med nye værdier.

Variablerne:

– IntervalDays

– InterValMonths

– NextCaptureDate

opdateres kun hvis ikke de er tomme / ikke har nogen værdi.

Når en opdatering af eksisterende abonnementer er gennemført, vil den / disse få en RecurringReturnStatus = 4, og dermed sende et http svar tilbage:

201 – Subscribtion #123 successfull Pre-aut Update

1

Det er vigtig at bemærke, at der er væsentlig forskel på håndtering af abonnementsbetalinger med PayApi.asp i forhold til SecureCapture.asp da PayApi.asp typisk benyttes “backend”, i forhold til SecureCapture.asp hvor kunder betaler via frontend / hjemmeside mv.

Fjernhævning af abonnementsbetalinger

Hvis der bruges “Recurringcapture” som i nedenstående eksempel, vil abonnementsbetalinger automatisk forlænges – og dermed ikke længere fremgå over dem der er forfaldne, samt abonnementsbetalingen vil være gennemført.

Eksempelfil Beskrivelse

Download

remote_recurring_capture.txt Filen indeholder mulighed for at “hæve”, en eksisterende abonnementsbetaling.

Download

 

Kodeeksempel på http kald med til payapi.asp

Følgende læser en status ud på en transaktion der er foretaget og ligger i betalingssystemet: