Generelt
PayApi Webservice giver adgang til værktøjer, typisk brugbare i forbindelse med integrering af online betalinger på intranet, extranet, abonnementsbetalinger, hævning / delhævning mv. hvor der ønskes at undgå login til https://pay.onlinepayment.dk administrationen.
Filnavn: PayApi.asp
Det er muligt at foretage en remote capture altså en fjernhåndtering af betalinger der er gået ind online og afventer yderligere behandling. Det vil sige, at hæve en transaktion blot ved et enkelt http kald. Dette kan indbygges i eks. ERP systemer, Intranet eller andet. Det eneste krav er blot at der laves et http kald.
URL'en til at lave et kald til webservicen består af:
https://pay.onlinepayment.dk/PayApi.asp?username=yyyyyyy&password=xxxxxxx
Husk at ændre yyyyyyy og xxxxxxxx til hhv. brugernavn og password der normalt benyttes til at logge ind i betalingssystem administrationen
Eksempel: https://pay.onlinepayment.dk/PayApi.asp?username=yyyyyyy&password=xxxxxxx&capture=1&orderid=1020
I ovenstående eksempel vil der blive hævet en eksisterende transaktion med ordre id 1020 dersom "capture" er sat til værdien 1.
Til denne kan så tilføjes yderligere parametre, eksempelvis hvis der ønskes udført andre funktioner sammen med hævning af beløbet.
Eksempelvis en nedjustering af beløbet der hæves. Dette vil så for eksemplets skyld se således ud og nedjustere beløbet fra det oprindelige beløb til $22,- (valuta for betalingen kan ikke ændres)
https://pay.onlinepayment.dk/PayApi.asp?username=yyyyyyy&password=xxxxxxx&capture=1&orderid=1020&ChangeAmount=1&Amount=22
|
Parameter
|
Beskrivelse
|
|
Username
|
Forretningens unikke id. Tildelt af PBS (Krævet)
|
|
Password
|
Password som normalt bruges til at logge ind i betalingssystemet (Krævet)
|
|
Capture
|
Skal altid være "1" for at hæve (Krævet)
|
|
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
|
Hvis denne sættes til "1" vil den validere om beløbet på transaktionen stemmer overens med det angivet i "amount" parametren. (valgfri)
|
|
ChangeAmount
|
Hvis denne sættes 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. (valgfri)
|
|
Amount
|
Denne skal udfyldes med beløbet hvis "DoAmountCheck" eller "ChangeAmount" sættes til "1"
(valgfri)
|
|
|
|
Funktioner
I tillæg til ovenstående findes også mulighed for visning af statuskoder. Disse er for de enkelte kald (Capture, Renew, Reject) defineret således:
|
Parameter
|
Beskrivelse
|
Format
|
|
Capture (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
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.
|
|
Kontrol af transaktioners status
Eksempel: https://pay.onlinepayment.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
|
Specielt for abonnementsbetalinger
Der gælder specielle parametre til https://pay.onlinepayment.dk/PayApi.asp, også i tillæg til ovenstående. Her gælder også at brugernavn og password skal sendes med i kommandoen til betalingsserveren. Udgangspunktet er derfor stadig :
https://pay.onlinepayment.dk/PayApi.asp?username=yyyyyyy&password=xxxxxxx
når der forsøges at ændre eller kalde eksisterende abonnementer.
Nedenstående benyttes typisk 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.onlinepayment.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
|
Det er meget 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.
Opdatering af eksisterende abonnementer
Det er muligt ved kald af "PreAuthRecurring" på både payapi.asp og securecapture.asp at medsende "UpdateExistingSubscriber" med værdien "1" for at opdatere eksisterende abonnement, hvor der ellers, hvis værdien er "0" eller ikke eksisterende, vil blive indsat / oprettet et nyt abonnement.
Forklaret i tekst, vil:
<input type="hidden" name="UpdateExistingSubscriber" value="1">
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
Summerede funktioner
Opdelt i hovedgrupper kan PayApi'et:
Optional / valgfri:
Optional / valgfri:
Kode eksempler på http kald med asp til payapi.asp
Følgende eksempelkode læser en status ud på en transaktion der er foretaget og ligger i betalingssystemet:
<%
dim XMLHTTPobj,PageUrl
PageUrl = "https://pay.onlinepayment.dk/payapi.asp?username=xxxxxxx&password=xxxxxxx&Checkstatus=1&OrderID=xxxxxx"
set XMLHTTPobj = server.CreateObject("Msxml2.ServerXMLHTTP.6.0")
XMLHTTPobj.open "GET", PageUrl,false
XMLHTTPobj.send
response.write XMLHTTPobj.responseText
set XMLHTTPobj = nothing
%>