1. Home
2. Integratie- oplossingen
3. Integraties
4. DirectLink

1. Introductie

Worldline DirectLink biedt u de mogelijkheid om server-to-server integratie met ons platform op te zetten. De klant blijft op een van uw pagina's, die de betaalgegevens beveiligd naar onze servers stuurt.

U kunt DirectLink ook gebruiken voor onderhoud op transacties, ongeacht of die werden gestart in DirectLink of bv. in Gehoste betaalpagina-modus.

Het schema hierboven laat een transactieflow met DirectLink zien.

Met DirectLink komt de klant van de handelaar (uw klant) niet in aanraking met ons systeem. Uw systeem stuurt alle nodige informatie voor de betaling rechtstreeks naar ons systeem in een HTTPS POST-verzoek. Ons systeem vraagt de financiële transactie (synchroon of asynchroon) aan bij de desbetreffende acquirer en stuurt het antwoord terug naar uw server in XML-formaat. Uw programma leest het antwoord en gaat voort met de verwerking. Bijgevolg bent u verantwoordelijk voor het verzamelen en bewaren van de vertrouwelijke betaalgegevens van uw klant en moet u de vertrouwelijkheid en beveiliging van die gegevens garanderen door middel van versleutelde internetcommunicatie en serverbeveiliging. Om persoons- en kaartgegevens op te slaan, moet u PCI-conform zijn.

2. Algemene procedures en veiligheidsinstellingen

Deze algemene procedures en veiligheidscontroles gelden voor alle DirectLink-verzoeken: nieuwe bestellingsverzoeken, onderhoudsverzoeken en rechtstreekse opvragingen.

Het schema hierboven laat een stap-voor-stap transactieflow met DirectLink zien.

2.1 API-gebruiker

Er is een API-gebruiker (Application Program Interface) nodig om DirectLink-verzoeken mee aan te maken.

Dat is een gebruiker die specifiek wordt aangemaakt zodat een toepassing er automatische verzoeken aan het betaalplatform mee kan sturen.

U kunt een API-gebruiker aanmaken in uw Worldline-account via 'Configuratie' > 'Gebruikers'. Kies 'Nieuwe gebruiker' en vul de verplichte velden in.

Om van de nieuwe gebruiker een API-gebruiker te maken, vinkt u het vakje 'Special user for API (no access to admin.)' (Speciale gebruiker voor API (geen toegang tot beheer)) aan.

Hoewel voor een API-gebruiker de diverse gebruikersprofielen beschikbaar zijn, raden wij u ten zeerste aan deze gebruiker te configureren met het profiel 'Admin'. Als u de rechten voor het onderhoud van transacties (terugbetalingen, annuleringen enz.) wilt beperken, kunt u het gebruikersprofiel later nog wijzigen, bv. in 'Encoder'. Als u twijfelt, raden we u aan het profiel 'Admin' te kiezen of de Gebruikersprofielen (User Manager) te bekijken voor meer informatie. Het wachtwoord van een API-gebruiker hoeft niet regelmatig te worden gewijzigd. Dat is gemakkelijker wanneer het wachtwoord expliciet moet worden opgenomen in de code van uw toepassing. Wij raden u echter aan het wachtwoord van tijd tot tijd te wijzigen. Meer informatie over soorten gebruikers en hoe u het wachtwoord van de API-gebruiker wijzigt, vindt u in Soorten gebruikers (User Manager).

2.2 Verzoekformulier

Voor nieuwe bestellingsverzoeken, onderhoudsverzoeken en rechtstreekse opvragingen moet u verzoeken met bepaalde parameters naar specifieke URL's sturen. De parameters van uw nieuwe bestelling / onderhoud / opvraging moeten als volgt worden verstuurd in een POST-verzoek:

PSPID=waarde1&USERID=waarde2&PSWD=waarde3&…

Het type/subtype dat het mediatype aangeeft in het veld Content Type in de header van het POST-verzoek, moet 'application/x-www-form-urlencoded' zijn.

DirectLink werkt volgens de modus “één verzoek – één antwoord”: elke betaling wordt afzonderlijk verwerkt. Ons systeem verwerkt individuele transactieverzoeken via DirectLink en kan synchroon werken (als die optie technisch ondersteund wordt). Dat wil zeggen dat we wachten op het antwoord van de bank alvorens een XML-antwoord op het verzoek te sturen.

2.3 Veiligheid

Wanneer wij een verzoek op onze servers ontvangen, controleren wij de versleuteling en het IP-adres van waar het verzoek werd verzonden.

2.3.1 Versleuteling

DirectLink maakt gebruik van een solide, veilig communicatieprotocol. De API is een reeks instructies die worden ingediend met standaard HTTPS POST-verzoeken. Handelaars mogen alleen met ons verbinding maken in beveiligde https-modus.
Aan clientzijde is geen TLS-certificaat nodig.

2.3.2 SHA-handtekening

De SHA-handtekening werkt volgens het principe dat uw server (de server van de handelaar) voor elke bestelling een unieke tekenreeks aanmaakt, die wordt gehasht met het algoritme SHA-1, SHA-256 of SHA-512. Het resultaat van die hash wordt vervolgens naar ons gestuurd in uw bestellingsverzoek. Ons systeem herberekent die handtekening om de integriteit te controleren van de bestellingsgegevens die we in het verzoek ontvingen.

Meer informatie vindt u in SHA-IN-versleuteling (Worldline Gehoste betaalpagina-documentatie) - het principe is identiek in Gehoste betaalpagina- en DirectLink-modus.

Voor DirectLink moet de SHA-IN-wachtzin geconfigureerd worden in de sectie 'Verificatie voor Worldline DirectLink...' van het tabblad 'Verificatie data en herkomst' op de pagina 'Technische instellingen'.

2.3.3 IP-adres

Voor elk verzoek controleert ons systeem het IP-adres van waar het verzoek afkomstig is om er zeker van te zijn dat de verzoeken worden verzonden vanaf uw server (de server van de handelaar). U moet, op de pagina 'Technical instellingen' van uw account, in het veld IP-adres in de sectie 'Verificatie voor Worldline DirectLink...' van het tabblad 'Verificatie data en herkomst', de IP-adressen of IP-adresbereiken opgeven van de servers die uw verzoeken sturen.

Als het IP-adres van oorsprong niet werd opgegeven in het voorziene veld 'IP-adres', krijgt u de foutboodschap “unknown order/1/i/”. Het IP-adres van waar het verzoek werd verzonden, wordt ook weergegeven in het foutbericht.

2.4 Verwerking van het antwoord

Wij sturen een XML-antwoord op uw verzoek. Let erop dat uw systemen dit XML-antwoord zo tolerant mogelijk verwerken om later problemen te voorkomen: vermijd hoofdlettergevoelige attribuutnamen, leg geen specifieke volgorde voor de teruggezonden attributen in antwoorden op, zorg ervoor dat nieuwe attributen in het antwoord geen fouten genereren enz.

3. Een nieuw bestellingsverzoek indienen

3.1 Verzoek-URL

• De verzoek-URL in de TEST-omgeving is https://ogone.test.v-psp.com/ncol/test/orderdirect.asp.
• De verzoek-URL in de PRODUCTIE-omgeving is https://secure.ogone.com/ncol/prod/orderdirect.asp.

Vervang 'test' door 'prod' Vervang “test” door “prod” in de verzoek-URL wanneer u overstapt op uw productie-account. Als u vergeet de verzoek-URL te wijzigen wanneer u in productie begint te werken met echte bestellingen, worden uw transacties verstuurd naar de testomgeving en niet verwerkt door de acquirers / banken.

3.2 Verzoekparameters

Onderstaande tabel bevat de verzoekparameters voor het versturen van een nieuw bestellingsverzoek:

Veld	Omschrijving
PSPID	De naam waaronder u bent geregistreerd in ons systeem. Formaat: AN, 30 Verplicht
ORDERID	Uw unieke bestellingsnummer (referentie van de handelaar). Formaat: AN, 40 Verplicht
USERID	Naam van uw applicatiegebruiker (API-gebruiker). Meer informatie over hoe u een API-gebruiker aanmaakt, vindt u in de User Manager-documentatie. Formaat: AN, 20 (min. 2) Verplicht
PSWD	Wachtwoord van de API-gebruiker (USERID). Formaat: AN Verplicht
AMOUNT	Te betalen bedrag, VERMENIGVULDIGD MET 100, aangezien het formaat van het bedrag geen decimaaltekens of andere scheidingstekens mag bevatten. Formaat: N, 15 Verplicht
CURRENCY	Valuta van de bestelling in ISO-lettercode, bijvoorbeeld: EUR, USD, GBP, CHF enz. Formaat: AN, 3 Verplicht
CARDNO	Kaart- / rekeningnummer. Formaat: AN, 21 Verplicht
ED	Vervaldatum. Formaat: MM/JJ of MMJJ Verplicht
COM	Beschrijving van de bestelling. Formaat: AN, 100 Optioneel
CN	Naam van de klant. Formaat: AN, 35 Verplicht
EMAIL	E-mailadres van de klant. Als je 3DSv2.1 aanvraagt, zorg er dan voor dat het format van de e-mail geldig is, anders valt het authenticatieproces terug naar 3DS 1.0 Formaat: AN, 50 Optioneel
SHASIGN	Handtekening (gehashte tekenreeks) om de gegevens te authenticeren (zie SHA-IN-versleuteling). Formaat: AN, 128 Verplicht
CVC	Kaartverificatiecode (Card Verification Code). Afhankelijk van het merk van de kaart is de verificatiecode een code van 3 of 4 cijfers op de voor- of achterkant van de kaart, een uitgiftenummer, een startdatum of een geboortedatum. Formaat: N, 5 Verplicht
ECOM_PAYMENT_ CARD_VERIFICATION	Alternatief voor de kaartverificatiecode: geboortedatum / uitgiftenummer / enz. (afhankelijk van uw land of bank) Formaat: N, 5 Optioneel
OWNERADDRESS	Straatnaam en huisnummer van de klant. Formaat: AN, 50 Optioneel
OWNERZIP	Postcode van de klant. Formaat: AN, 10 Optioneel
OWNERTOWN	Gemeente of stad van de klant. Formaat: AN, 40 Optioneel
OWNERCTY	Land van de klant, bv. BE, NL, FR enz. Formaat: AN, 2 Optioneel
OWNERTELNO	Telefoonnummer van de klant. Formaat: AN, 30 Optioneel
OPERATION	Bepaalt het type gevraagde transactie. U kunt een standaardbewerking configureren (betaalprocedure) in de sectie 'Default operation code' (Standaard bewerkingscode) van het tabblad 'Global transaction parameters' (Algemene transactieparameters') op de pagina 'Technical Information' (Technische informatie). Wanneer u in het verzoek een bewerkingscode verzendt, overschrijft die de standaardwaarde. Mogelijke waarden: RES: verzoek om autorisatie SAL: verzoek om directe verkoop RFD: terugbetaling, niet gekoppeld aan een voorafgaande betaling, dus geen onderhoudsbewerking voor een bestaande transactie (u kunt deze bewerking niet gebruiken zonder specifieke toelating van uw acquirer). Optioneel: PAU: verzoek om pre-autorisatie: In overleg met uw acquirer kunt u deze bewerkingscode gebruiken om tijdelijk een bedrag op de kaart van een klant te reserveren. Dat is een courante praktijk in de reis- en verhuurbranche. PAU / pre-autorisatie kan momenteel alleen gebruikt worden voor MasterCard-transacties en wordt door een beperkt aantal acquirers ondersteund. U kunt deze bewerkingscode niet instellen als standaard in uw Worldline-account. Als u PAU gebruikt voor transacties via acquirers of met kaartmerken die pre-autorisatie niet ondersteunen, worden die transacties niet geblokkeerd, maar verwerkt als normale (RES) autorisaties. Formaat: A, 3 Verplicht
WITHROOT	Voegt een root-element toe aan ons XML-antwoord. Mogelijke waarden: ‘Y’ of leeg. Formaat: Y of <leeg> Optioneel
REMOTE_ADDR	IP-adres van de klant (alleen voor fraudedetectiemodule). Als geen landcontrole moet worden uitgevoerd op het IP-adres, stuurt u 'NONE'. Formaat: AN Optioneel
RTIMEOUT	Time-out van het verzoek voor de transactie (in seconden, waarde tussen 30 en 90) Belangrijk: de waarde die u hier instelt, moet kleiner zijn dan de time-outwaarde in uw systeem (!) Formaat: N, 2 Optioneel
ECI	Electronic Commerce Indicator (E-commerce indicator - ECI). U kunt een standaard ECI-waarde configureren op de accountpagina 'Technical information' (Technische informatie), tabblad 'Global transaction parameters' (Algemene transactieparameters), sectie 'Default ECI value' (Standaard ECI-waarde). Wanneer u in het verzoek een ECI-waarde verzendt, overschrijft die de standaard ECI-waarde. Mogelijke (numerieke) waarden: 0 - Doorgehaald 1 - Handmatig ingevoerd (MOTO) (kaart niet aanwezig) 2 - Herhaling (van MOTO) 3 - Afbetalingen 4 - Handmatig ingevoerd, kaart aanwezig 7 - E-commerce met SSL-codering 9 - Herhaling (van e-commerce) Formaat: N, 2 Optioneel

Als je terugkerende betalingen verwerkt, moet je Credentials-on-file (COF)-parameters aan je verzoek toevoegen.

Zie onze Alias Manager-handleiding voor meer informatie over het verwerken van COF-transacties.



De lijst van mogelijk te versturen parameters kan langer zijn voor handelaars die in hun account bepaalde opties of functies geactiveerd hebben. Raadpleeg de documentatie van de desbetreffende optie voor meer informatie over extra parameters die aan de optie gekoppeld zijn.

Volgende verzoekparameters zijn verplicht voor nieuwe bestellingen:

• PSPID en USERID
• PSWD
• ORDERID
• AMOUNT (x 100)
• CURRENCY
• CARDNO
• ED
• CVC
• OPERATION

Voldoen aan de merkkeus van de klant voor kaarten met co-badging In sommige gevallen wordt een creditcard van een internationale regeling (bijv. Visa / MasterCard) ook uitgegeven voor een tweede, lokale betalingsmethode. Dergelijke creditcards worden ook wel creditcards met co-badging of multimerkkaarten genoemd. Als je lokale betalingsmethodes aanbiedt naast de internationale regelingen, moet je de klant de mogelijkheid geven te kiezen tussen de merken waarvoor een multimerkkaart is uitgegeven. Om dit te doen, moet je ervoor zorgen dat Je de lokale betalingsmethode beschikbaar hebt in je backoffice onder Configuratie > Betaalmethoden. Als je Visa / MasterCard aanbiedt via een Franse verwerver, hebben we Card Bancaire (CB) al voor je toegevoegd. Onze klantendienst helpt je graag bij het toevoegen van meer betalingsmethoden De klant kan kiezen tussen de merken in je webshop en de betalingsvorm die aan jouw kant wordt gehost, wordt navenant aangepast. Gebruik de parameters PM / BRAND om de keus van de klant aan te geven  (Je vindt een lijst met alle beschikbare waarden voor deze parameters in het backoffice).

3.3 Testpagina

Onze testpagina om bestellingsverzoeken te versturen in DirectLink vindt u hier: https://ogone.test.v-psp.com/ncol/test/testodl.asp.

3.4 Specifieke betaalmethoden uitsluiten

Als er betaalmethoden zijn die u een klant niet ter beschikking wilt stellen, kunt u dat doen met behulp van een parameter.
Dit is vooral handig voor submerken, wanneer u een merk (bijvoorbeeld MasterCard) wilt aanvaarden, maar niet één van de submerken ervan (bijvoorbeeld Maestro).

Dit is de parameter:

Veld	Gebruik
EXCLPMLIST	Lijst van betaalmethoden en/of creditcardmerken die NIET mogen worden gebruikt. U moet de waarden van elkaar scheiden met een “;” (puntkomma).

Als een klant probeert te betalen met een kaart die gelinkt is aan een betaalmethode die en/of een (sub)merk dat u met de parameter EXCLPMLIST hebt uitgesloten, wordt het foutbericht “Card number incorrect or incompatible” (Kaartnummer onjuist of niet compatibel) teruggestuurd met het veld NCERRORPLUS.

3.5 Bestellingsverzoek met behulp van 3-D Secure

Ons systeem ondersteunt het gebruik van 3-D Secure met DirectLink.

Belangrijk Als u 3-D Secure met DirectLink wenst te gebruiken, dan moet u de optie D3D in uw account geactiveerd hebben. "> Sommige acquirers vereisen het gebruik van 3-D Secure. Vraag na bij uw acquirer of dit voor u het geval is.

3.6 Credit-/debitcards splitsen

De functie om VISA en MasterCard te splitsen in een debit- en een creditbetaalmethode stelt u in staat om ze aan uw klanten aan te bieden als twee verschillende betaalmethoden (bv. VISA Debit en VISA Credit). U kunt ook beslissen om van beide gesplitste merken slechts één optie te aanvaarden.

Om de splitsing in credit- en debitcards te gebruiken via DirectLink moet u de parameter CREDITDEBIT opnemen in de velden die u naar de pagina orderdirect.asp stuurt (en dus ook in de SHA-IN-berekening!).

Veld	Formaat
CREDITDEBIT	"C": creditcard "D": debitcard

Aanverwante fout: als de koper debitcard kiest als betaalmethode en vervolgens een creditcardnummer invoert, wordt een foutcode teruggestuurd: ‘Wrong brand/Payment method was chosen’ (Verkeerd merk / betaalmethode gekozen).

Als de betaling met succes verwerkt is met de parameter CREDITDEBIT wordt dezelfde parameter ook teruggestuurd in het XML-antwoord en/of kan hij worden opgevraagd met een rechtstreekse opvraging. Terwijl de ingediende waarde echter C of D is, is de teruggestuurde waarde 'CREDIT' of 'DEBIT'.

U vindt die teruggestuurde waarden ook in het transactieoverzicht via 'Beheer transacties' en 'Financiële historiek/Dagtotalen' en in rapporten die u nadien kunt downloaden.

Configuratie in uw account In uw Worldline-account kunt u de functie 'splitsen' ook activeren en configureren per betaalmethode. Ga naar Split credit/debit cards voor meer informatie.

3.7 Transacties met opgeslagen referenties verwerken

Zie onze Alias Manager-handleiding voor meer informatie over het verwerken van COF-transacties.

4. Antwoord op een bestelling

Onze server stuurt een XML-antwoord op elk verzoek:

Voorbeeld van een XML-antwoord op een bestellingsverzoek <?xml version=”1.0”?> <ncresponse orderID=”99999” PAYID=”1111111” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS=”5” ECI=”7” amount="125" currency="EUR" PM="CreditCard" BRAND="VISA"/>

Onderstaande tabel bevat een lijst van de ncresponse-tagattributen:

Veld	Omschrijving
ACCEPTANCE	De door de acquirer teruggestuurde aanvaardingscode.
amount	Bedrag van de bestelling (niet vermenigvuldigd met 100).
BRAND	Kaartmerk of gelijkaardige informatie voor andere betaalmethoden.
currency	Valuta van de bestelling.
ECI	Electronic Commerce Indicator (E-commerce indicator - ECI).
NCERROR	Foutcode.
NCERRORPLUS	Verklaring van de foutcode.
NCSTATUS	Eerste teken van NCERROR.
orderID	Uw bestellingsreferentie.
PAYID	Betalingsreferentie in ons systeem.
PM	Betaalmethode.
STATUS	Transactiestatus. (Mogelijke statussen)

De attributenlijst kan langer zijn voor handelaars die in hun account bepaalde opties (zoals Fraudedetectie) hebben geactiveerd. Raadpleeg de documentatie van de desbetreffende optie voor meer informatie over extra antwoordattributen die aan de optie gekoppeld zijn.

4.1 Dubbel verzoek

Als u de verwerking aanvraagt van een reeds bestaande (en correct verwerkte) orderID, bevat ons XML-antwoord de PAYID die overeenkomt met de bestaande orderID, de ACCEPTANCE die de acquirer gaf bij de vorige verwerking, de STATUS “0” en NCERROR “50001113”.

5. Rechtstreeks onderhoud

Met een rechtstreeks onderhoudsverzoek van uw toepassing kunt u:

• De gegevens (betaling) van een geautoriseerde bestelling automatisch registreren (in plaats van handmatig in de backoffice);
• De autorisatie van een bestelling annuleren;
• De autorisatie van een bestelling vernieuwen;
• Een betaalde bestelling terugbetalen;

Gegevensregistratie, annulering van autorisaties en vernieuwing van autorisaties zijn specifiek voor handelaars die hun account / verzoeken hebben geconfigureerd om de autorisatie en gegevensregistratie in twee stappen uit te voeren.

5.1 Onderhoudsverzoek

5.1.1 Verzoek-URL

• De verzoek-URL in de TEST-omgeving is https://ogone.test.v-psp.com/ncol/test/maintenancedirect.asp.
• De verzoek-URL in de PRODUCTIE-omgeving is https://secure.ogone.com/ncol/prod/maintenancedirect.asp.

Vervang 'test' door 'prod' Vervang “test” door “prod” in de verzoek-URL wanneer u overstapt op uw productie-account. Als u vergeet de verzoek-URL te wijzigen wanneer u begint te werken met echte bestellingen, worden uw onderhoudstransacties verstuurd naar de testomgeving en niet verstuurd naar de acquirers / banken.

5.1.2 Verzoekparameters

Onderstaande tabel bevat de verplichte verzoekparameters om een onderhoudsbewerking uit te voeren:

Veld	Omschrijving
AMOUNT	Bedrag van de bestelling vermenigvuldigd met 100. Dit is alleen verplicht als het bedrag van het onderhoud verschilt van het bedrag van de oorspronkelijke autorisatie. Wij raden echter aan om deze parameter altijd te gebruiken. Ons systeem zal controleren of het bedrag van de onderhoudstransactie niet groter is dan het bedrag van de autorisatie / betaling.
OPERATION	Mogelijke waarden: REN: autorisatie vernieuwen, als de oorspronkelijke autorisatie niet langer geldig is. DEL: autorisatie verwijderen, waarna de transactie blijft openstaan voor eventuele latere onderhoudsbewerkingen. DES: autorisatie verwijderen, waarna de transactie wordt afgesloten. SAL: gedeeltelijke gegevensregistratie (betaling), waarna de transactie blijft openstaan voor een eventuele volgende gegevensregistratie. SAS: (laatste) gedeeltelijke of volledige gegevensregistratie (betaling), waarna de transactie wordt afgesloten (voor verdere gegevensregistratie). RFD: gedeeltelijke terugbetaling (van een betaalde bestelling), waarna de transactie blijft openstaan voor een eventuele volgende terugbetaling. RFS: (laatste) gedeeltelijke of volledige terugbetaling (van een betaalde bestelling), waarna de transactie wordt afgesloten. Merk voor DEL en DES op dat niet alle acquirers de verwijdering van een autorisatie ondersteunen. Als uw acquirer DEL / DES niet ondersteunt, zullen wij niettemin de verwijdering van de autorisatie simuleren in de backoffice.
ORDERID	U kunt de PAYID of de orderID sturen om de oorspronkelijke bestelling te identificeren. Wij raden u aan de PAYID te gebruiken.
PAYID
PSPID	De PSPID van uw account.
PSWD	Het wachtwoord van uw API-gebruiker.
SHASIGN	Handtekening (gehashte tekenreeks) om de gegevens te authenticeren (zie SHA-IN-versleuteling).
USERID	Uw API-gebruiker.

5.2 Antwoord op een onderhoudsverzoek

Onze server stuurt een XML-antwoord op het onderhoudsverzoek:

Voorbeeld van een XML-verzoek op een rechtstreeks onderhoudsverzoek <?xml version=”1.0”?> <ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="91" amount="125" currency="EUR"/>

Onderstaande tabel bevat een lijst van de ncresponse-tagattributen:

Veld	Omschrijving
ACCEPTANCE	De door de acquirer teruggestuurde aanvaardingscode
AMOUNT	Bedrag van de bestelling (niet vermenigvuldigd met 100)
CURRENCY	Valuta van de bestelling
NCERROR	Foutcode
NCERRORPLUS	Verklaring van de foutcode
NCSTATUS	Eerste teken van NCERROR
ORDERID	De referentie van uw bestelling
PAYID	Betalingsreferentie in ons systeem
PAYIDSUB	De identificatie van het historiekniveau van de onderhoudsbewerking op de PAYID
STATUS	Transactiestatus (Mogelijke statussen)

De standaard ncresponse-tagattributen zijn dezelfde als voor het XML-antwoord op een nieuwe bestelling, met uitzondering van het extra attribuut PAYIDSUB.

5.3 Dubbel verzoek

Als u tweemaal om onderhoud verzoekt voor dezelfde bestelling, wordt het tweede verzoek in theorie geweigerd met foutcode “50001127” (Bestelling niet geautoriseerd), aangezien de eerste, geslaagde transactie de status van de bestelling heeft gewijzigd.

6. Rechtstreekse opvraging

Met een verzoek om rechtstreekse opvraging vanuit uw toepassing kunt u de status van een bestelling automatisch opvragen (in plaats van handmatig in de backoffice). U kunt slechts één betaling per keer opvragen, en u ontvangt slechts een beperkt aantal gegevens over de bestelling.

Als u meer informatie over de bestelling nodig hebt, kunt u de transactie opzoeken in de backoffice of een handmatige of automatische bestandsdownload uitvoeren (zie Uw transacties raadplegen en Batch).

6.1 Opvragingsverzoek

6.1.1 Verzoek-URL

• De verzoek-URL in de TEST-omgeving is https://ogone.test.v-psp.com/ncol/test/querydirect.asp.
• De verzoek-URL in de PRODUCTIE-omgeving is https://secure.ogone.com/ncol/prod/querydirect.asp.

Vervang 'test' door 'prod' Vervang “test” door “prod” in de verzoek-URL wanneer u overstapt op uw productie-account.

6.1.2 Verzoekparameters

Onderstaande tabel bevat de verplichte verzoekparameters om een rechtstreekse opvraging uit te voeren:

Veld	Omschrijving
ORDERID	U kunt de PAYID of de ORDERID sturen om de oorspronkelijke bestelling te identificeren. Wij raden u aan de PAYID te gebruiken.
PAYID
PAYIDSUB	U kunt de identificatie van het historiekniveau vermelden als u de PAYID gebruikt om de oorspronkelijke bestelling te identificeren (optioneel).
PSPID	De PSPID van uw account.
PSWD	Het wachtwoord van uw API-gebruiker.
USERID	Uw API-gebruiker.

6.1.3 Testpagina

Rechtstreekse opvragingsverzoeken kunt u hier testen: https://ogone.test.v-psp.com/ncol/test/testdq.asp.

6.2 Antwoord op een opvraging

Onze server stuurt een XML-antwoord op het verzoek:

Voorbeeld van een XML-antwoord op een rechtstreekse opvraging <?xml version=”1.0”?> <ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="9" ECI=”7” amount="125" currency="EUR" PM="CreditCard" BRAND="VISA" CARDNO="XXXXXXXXXXXX1111" IP="212.33.102.55"/>

Onderstaande tabel bevat een lijst van de ncresponse-tagattributen:

Veld	Gebruik
ACCEPTANCE	De door de acquirer teruggestuurde aanvaardingscode
amount	Bedrag van de bestelling (niet vermenigvuldigd met 100)
BRAND	Kaartmerk of gelijkaardige informatie voor andere betaalmethoden
CARDNO	Het gemaskeerde creditcardnummer
currency	Valuta van de bestelling
ECI	Electronic Commerce Indicator (E-commerce indicator - ECI)
IP	IP-adres van de klant, door ons systeem gedetecteerd in een 3-lagige integratie, of door de handelaar naar ons verzonden in een 2-lagige integratie
NCERROR	Foutcode
NCERRORPLUS	Verklaring van de foutcode
NCSTATUS	Eerste teken van NCERROR
orderID	De referentie van uw bestelling
PAYID	Betalingsreferentie in ons systeem
PAYIDSUB	De identificatie van het historiekniveau van de onderhoudsbewerking op de PAYID
PM	Betaalmethode
STATUS	Transactiestatus

De standaard ncresponse-tagattributen zijn dezelfde als voor het XML-antwoord op een nieuwe bestelling, met uitzondering van de extra attributen PAYIDSUB, CARDNO en IP.

De attributenlijst kan langer zijn voor handelaars die in hun account bepaalde opties (zoals Fraudedetectie) hebben geactiveerd. Raadpleeg de documentatie van de desbetreffende optie voor meer informatie over extra antwoordattributen die aan de optie gekoppeld zijn.

6.2.1 Transacties verwerkt met Gehoste betaalpagina (gehoste betaalpagina)

Als de transactie waarvan u de status wilt controleren werd verwerkt met Gehoste betaalpagina (gehoste betaalpagina), ontvangt u mogelijk ook de volgende extra attributen (op voorwaarde dat u die velden hebt meegestuurd bij de oorspronkelijke Gehoste betaalpagina-transactie).

Veld	Omschrijving
complus*	Een waarde die u wou laten terugsturen
(paramplus content)*	De parameters en hun waarden die u wou laten terugsturen

*Zie de Variabele feedbackparameters (Gehoste betaalpagina-documentatie).

Voorbeeld van een XML-antwoord op een rechtstreekse opvraging voor een Gehoste betaalpagina-transactie <ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="9" amount="125" currency="EUR" PM="CreditCard" BRAND="VISA" CARDNO="XXXXXXXXXXXX1111" IP="212.33.102.55" COMPLUS="123456789123456789123456789" SessionID="126548354" ShopperID="73541312"/>

6.3 Mogelijke antwoordstatussen

Het veld STATUS bevat de status van de transactie (zie Mogelijke statussen).

Alleen de volgende status houdt specifiek verband met de opvraging zelf:

Status	NCERROR	NCSTATUS	Omschrijving
88			De opvraging op querydirect.asp is mislukt

6.4 Rechtstreekse opvraging als controle

De responstijd voor een DirectLink-transactieverzoek bedraagt doorgaans enkele seconden; bij sommige acquirers kunnen de responstijden echter langer zijn.

Als u na 30 seconden van ons systeem geen antwoord hebt ontvangen, kunt u een verzoek sturen naar querydirect.asp om de status van uw recentste transactie naar orderdirect.asp op te vragen. Als u onmiddellijk antwoord krijgt met een niet-finale status voor de transactie, zijn er mogelijk problemen bij de acquirer.

Als u op die directe opvraging na 10 seconden nog geen antwoord hebt gekregen, zijn er mogelijk problemen bij ons. U kunt dit verzoek naar querydirect.asp elke 30 seconden herhalen tot u merkt dat u binnen 10 seconden een antwoord krijgt.

Opmerking Dit controlesysteem kan alleen problemen bij ons detecteren als er ook een controle bij u is om na te gaan of de verzoeken uw servers correct verlaten. Een probleem bij ons wordt niet noodzakelijkerwijs veroorzaakt door een defect, maar kan ook het gevolg zijn van lange responstijden, bijvoorbeeld vanwege databaseproblemen. Gebruik die controles oordeelkundig om onze servers niet te bombarderen met verzoeken, zo niet kunnen wij verplicht zijn uw toegang tot de pagina querydirect.asp te beperken.

Belangrijk Om ons systeem te beschermen tegen onnodige overbelasting verbieden wij controles op de werking van het systeem die valse transacties of systematische opvragingen sturen en systematische opvragingen om voor elke transactie feedback te krijgen.

7. Privacymeldingverzoek verwerkingsverantwoordelijke

Op basis van Artikel 12, 13 en 14 van de AVG heeft een verwerkingsverantwoordelijke de plicht eindgebruikers te informeren over de toekomstige verwerking van hun persoonsgegevens. Dergelijke informatie dient specifiek te zijn, afhankelijk van het soort persoonsgegevens dat moet worden ingevuld voor een specifieke transactie (zoals de geselecteerde betaalmethode, verwerkingsverantwoordelijke/verwerker, verwerver, fraude). Het resultaat moet inzichtelijk en zichtbaar zijn op het moment dat de gegevens worden verzameld en aan de kaarthouder moet een afdrukbare en downloadbare versie beschikbaar worden gesteld. Volgens het AVG-beleid moet u de informatie aan uw klant verstrekken voordat zij hun transactie valideren. Deze informatie moet idealiter worden weergegeven op dezelfde pagina als waar uw klant zijn kaart-/accountgegevens invult.
Met het onderstaande privacybeleidverzoek kunt u alle informatie opvragen die u nodig hebt om uw klanten over onze services te informeren om te voldoen aan de AVG-verordening.

7.1 Informeer hoe privacygegevens van een klant wordt verwerkt

7.1.1.1 Verzoek-URL

• De verzoek-URL in de TEST-omgeving is https://secure.ogone.com/ncol/test/privacy-policy.asp

Vervang "test" door "prod"

Vervang "test" door "prod" in de verzoek-URL wanneer u overstapt op uw productie-account.

7.1.1.2 Verzoekparameters

De volgende tabel bevat de verplichte verzoekparameters die naar uw klant moeten worden verzonden met betrekking tot het gebruik van hun privacygegevens:

Veld	Formaat	Beschrijving
USERID	String	Uw API-gebruiker
PSWD	String	Wachtwoord van uw API-gebruiker
PSPID	String	PSPID van uw account
BRAND	String (bijv. Visa)	Optioneel: Merk betaalmethode U kunt dit veld meerdere keren verzenden om het resultaat van verschillende merken tegelijk te krijgen. • Het verzenden van geen merk is hetzelfde als het verzenden van al uw actieve merken. • Lege/verkeerd geformatteerde merken worden genegeerd.
LANGUAGE	ISO 639-1: Tweelettercodes (bijv. FR)	Optioneel: De taal waarin de tekst wilt ophalen. Indien niet verstrekt wordt de tekst teruggestuurd naar de geconfigureerde taal van de merchant.

7.1.1.3 Testpagina

Rechtstreekse opvragingsverzoeken kunt u hier testen: https://secure.ogone.com/ncol/test/privacy-policy.asp

7.1.1 Verzoek-URL

• De verzoek-URL in de TEST-omgeving is https://secure.ogone.com/ncol/test/privacy-policy.asp

Vervang "test" door "prod"

Vervang "test" door "prod" in de verzoek-URL wanneer u overstapt op uw productie-account.

7.1.2 Verzoekparameters

De volgende tabel bevat de verplichte verzoekparameters die naar uw klant moeten worden verzonden met betrekking tot het gebruik van hun privacygegevens:

Veld	Formaat	Beschrijving
USERID	String	Uw API-gebruiker
PSWD	String	Wachtwoord van uw API-gebruiker
PSPID	String	PSPID van uw account
BRAND	String (bijv. Visa)	Optioneel: Merk betaalmethode U kunt dit veld meerdere keren verzenden om het resultaat van verschillende merken tegelijk te krijgen. • Het verzenden van geen merk is hetzelfde als het verzenden van al uw actieve merken. • Lege/verkeerd geformatteerde merken worden genegeerd.
LANGUAGE	ISO 639-1: Tweelettercodes (bijv. FR)	Optioneel: De taal waarin de tekst wilt ophalen. Indien niet verstrekt wordt de tekst teruggestuurd naar de geconfigureerde taal van de merchant.

7.1.3 Testpagina

Rechtstreekse opvragingsverzoeken kunt u hier testen: https://secure.ogone.com/ncol/test/privacy-policy.asp

7.2 Antwoord op een opvraging

De volgende is een lijst met XML-elementen en de teruggestuurde voorbeelden van XML-antwoorden voor verschillende resultaten.

Achternaam	Formaat	Beschrijving
Response	Complex	Hoofdknooppunt, altijd aanwezig
Response.Status	String, mogelijke waarden: Success, SuccessWithWarnings, Error	Altijd aanwezig
Response.Body	Complex	Altijd aanwezig als Response.Status = Success or SuccessWithWarnings
Response.Body.Html	String / html	Leeg als Response.Status = SuccessWithWarnings & Response.Warnings.Warning.Code = NoContent
Response.Errors	Complex	Alleen aanwezig als Response.Status = Error
Response.Errors.Error	Complex	Kan meerdere keren binnen een knooppunt <Errors> optreden
Response.Warnings	Complex	Alleen aanwezig als Response.Status = SuccessWithWarnings of Error
Response.Warnings.Warning	Complex	Kan meerdere keren binnen een knooppunt <Warnings> optreden
Response.Errors.Error.Code Response.Warnings.Warning.Code	String, mogelijke waarden: •Binnen een knooppunt <Error>: Unauthorized, InternalServerError •Binnen een knooppunt <Warning>: NoContent	Altijd aanwezig in een knooppunt <Error> of <Warning>
Response.Errors.Error.Message Response.Warnings.Warning.Message	String	Optioneel

Als u Response.Status=Error tegenkomt, raadpleegt u Response.Errors.Error om dit te verhelpen. Hierna volgen twee succesvolle voorbeelden:

1. Voorbeeld van een XML-antwoord voor succes met waarschuwingen. Het voorbeeld geeft als er geen privacygegevens bekend hoeven te worden gemaakt aan de klant. <?xml version="1.0" encoding="utf-8"?><Response>
<Status>SuccessWithWarnings</Status>
<Warnings>
<Warning>
<Code>NoContent</Code>
</Warning>
</Warnings>
<Body>
<Html/>
</Body>
</Response>

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Status>Success</Status>
<Body>
<Html><![CDATA[<ul><li><h2>Title 1</h2><p>Content 1</p></li><li><h2>Title 2 (VISA, American Express)</h2><p>Content 2</p></li></ul>]]></Html>
</Body>
</Response>

8. Uitzonderingen voor betaalmethoden

Voor sommige betaalmethoden wijken de parameterwaarden af van de standaard creditcardwaarden.

8.1 Automatische incasso

8.1.1 Automatische incasso Oostenrijk

Onderstaande tabel bevat de specifieke parameterwaarden voor de verzending van Oostenrijkse automatische incassotransacties via DirectLink.

Veld	Omschrijving	Formaat / Waarde
CARDNO	Bankrekeningnummer	AN, 21 Formaat: XXXXXXXXXXXBLZYYYYY XXXXXXXXXXX: rekeningnummer, numeriek, 11 cijfers. YYYYY: Bankcode (Bankleitzahl), 5 cijfers.
CN	Naam van de bankrekeninghouder	AN, 35
ED	Vervaldatum	„99/99“ of „9999“
OPERATION	Bewerkingscode (uit te voeren actie)	A, 3 Mogelijke waarden: RES: autorisatie SAL/SAS: bedrag debiteren van de bankrekening RFD/RFS: bedrag terugbetalen (*)
OWNERADDRESS	Adres van de rekeninghouder	AN, 50
OWNERTOWN	Gemeente / stad van de rekeninghouder	AN, 40
OWNERZIP	Postcode van de rekeninghouder	AN, 10
PM	Betaalmethode	AN, 25 “Direct Debits AT”

_{(*Als de optie Terugbetaling beschikbaar en geactiveerd is, en DTAUS-terugbetalingen beschikbaar zijn)}

8.1.2 Automatische incasso Duitsland (ELV)

Onderstaande tabel bevat de specifieke parameterwaarden voor de verzending van ELV-transacties via DirectLink. (niet Wirecard/Billpay)

Veld	Omschrijving	Formaat / Waarde	Verplicht
CARDNO	Bankrekeningnummer	IBAN: 22 alfanumerieke tekens OF Bankrekeningnummer + BLZ. Formaat: XXXXXXXXXBLZYYYYYYYY XXXXXXXXXX: rekeningnummer, numeriek, 1 tot 10 cijfers. YYYYYYYY: Bankcode (Bankleitzahl), 8 cijfers.	Ja
CN	Naam van de bankrekeninghouder	AN, 35	Ja
ED	Vervaldatum	„99/99“ of „9999“	Ja
MANDATEID	Unieke mandaatreferentie. Telego: Indien niet opgegeven gebruikt het platform de ORDERID of PAYID Opmerking: indien niet opgegeven genereert easycash een waarde.	Telego: AN, 35 / Tekenset: “A-Z a-z 0-9 spatie /-?:().,'+”) Indien niet opgegeven gebruikt het platform de ORDERID of PAYID Easycash: Formaat: AN, 27 / Tekenset: “A-Z a-z 0-9 spatie /-?:().,'+”) Opmerking: indien niet opgegeven genereert easycash een waarde.	Nee
OPERATION	Bewerkingscode (uit te voeren actie)	A, 3 Mogelijke waarden: RES: autorisatie SAL/SAS: bedrag debiteren van de bankrekening RFD/RFS: bedrag terugbetalen (*)	Nee
OWNERADDRESS	Straatnaam en huisnummer van de rekeninghouder	AN, 50	Ja
OWNERTOWN	Gemeente / stad van de rekeninghouder	AN, 40	Ja
OWNERZIP	Postcode van de rekeninghouder	AN, 10	Ja
PM	Betaalmethode	AN, 25 "Direct Debits DE”	Ja

Opmerking: Deze velden kunnen worden teruggestuurd in het DirectLink XML-antwoord en moeten worden opgenomen in de SHA-IN-berekening (optioneel ook SHA-OUT)

_{(*Als de optie Terugbetaling beschikbaar en geactiveerd is, en DTAUS-terugbetalingen beschikbaar zijn)}

8.1.3 Automatische incasso Nederland

Onderstaande tabel bevat de specifieke parameterwaarden voor de verzending van Nederlandse automatische incassotransacties via DirectLink.

Veld	Omschrijving	Formaat / Waarde
CARDNO	Bankrekeningnummer	Standaard Nederlands rekeningnummer: max. 10 alfanumerieke tekens (indien minder links uitvullen met nullen). OF IBAN-rekeningnummer: max. 35 alfanumerieke tekens (SEPA)
CN	Naam van de bankrekeninghouder	AN, 35
ED	Vervaldatum	„99/99“ of „9999“
OPERATION	Bewerkingscode (uit te voeren actie)	A, 3 Mogelijke waarden: SAL of SAS: bedrag debiteren van de bankrekening RFD of RFS: bedrag crediteren op de bankrekening (terugbetaling)
OWNERTOWN	Gemeente van de rekeninghouder	AN, 40
PM	Betaalmethode	AN, 25 “Automatische incasso Nederland”
Alleen relevant voor SEPA-transacties (*).
BIC	Bankidentificatiecode	AN, 11
MANDATEID	Unieke mandaatreferentie. Opmerking: Indien niet opgegeven wordt de ORDERID gebruikt.	AN, 35 Geen spaties; mag niet beginnen of eindigen met een schuine streep '/' en mag geen twee opeenvolgende schuine strepen bevatten.
SEQUENCETYPE	Het type automatische incassotransactie Opmerking: Indien niet opgegeven worden de transacties als “eenmalig” beschouwd en wordt de waarde 'OOFF' gebruikt.	Mogelijke waarden om het type automatische incassotransactie aan te geven (AN, 4): "FRST": Eerste inning van een reeks automatische incasso-opdrachten "RCUR": Automatische incasso-opdrachten waarbij de toestemming van de debiteur wordt gebruikt voor regelmatige automatische incassotransacties die door de crediteur worden geïnitieerd "FNAL": Laatste inning van een reeks automatische incasso-opdrachten (daarna kan dezelfde MandateID niet meer worden gebruikt) "OOFF": Automatische incasso-opdracht waarbij de toestemming van de debiteur wordt gebruikt om één enkele automatische incassotransactie te starten
SIGNDATE	Datum waarop het mandaat door de koper werd ondertekend. Opmerking: Indien niet opgegeven wordt de transactiedatum gebruikt.	JJJJMMDD

_{(*SEPA: Single Euro Payments Area - Gemeenschappelijke eurobetalingsruimte)}

Opmerking: Deze velden kunnen worden teruggestuurd in het DirectLink XML-antwoord en moeten worden opgenomen in de SHA-IN-berekening (en optioneel SHA-OUT).

8.2 Betaalmethoden met alleen onderhoud via DirectLink

Voor sommige betaalmethoden (uitgezonderd creditcards) kunt u geen nieuwe transacties versturen via DirectLink, maar kunt u bepaalde onderhoudsbewerkingen versturen via DirectLink. Dat is het geval voor PostFinance Card, PostFinance E-finance, PayPal Express Checkout en TUNZ.

Bij het versturen van onderhoudsbewerkingen zijn de velden PM, BRAND, CARDNO en ED niet verplicht, zodat voor die betaalmethoden geen specifieke waarden moeten worden verstuurd.

9. Veilige betaling met 3-D Secure

Raadpleeg onze PSD2-handleiding voor algemene informatie over 3-D Secure v2.

Leer hier hoe je 3-D Secure veilig kunt implementeren in het betalingsproces.

9.1 Transactiestroom van DirectLink 3-D Secure v2

De transactiestroom bestaat uit de volgende stappen:

1. Je klant gaat naar je afrekenpagina's en voltooit de aankoop op je betalingspagina.
2. Je stuurt de bestellingsinformatie en betalingsgegevens naar ons via een DirectLink-verzoek dat een aantal aanvullende parameters bevat.
   
   • (2') Optioneel: Wij voeren een fraudecontrole uit.
3. Je ontvangt een XML-respons van ons platform. Er zijn twee scenario's mogelijk.
   

   • Als de transactie via de wrijvingsloze flow gebeurt, bevat de respons de standaard parameters met de laatste transactiefeedback. Hiermee eindigt de flow.

   • Als de transactie via de challenge-flow gebeurt, bevat de respons het bijkomende veld HTML_ANSWER en een specifieke betalingsstatus (STATUS=46). HTML_ANSWER bevat een BASE64-gecodeerd codeblok.

4. Voeg het gedecodeerde codeblok toe aan de browser van de kaarthouder. De kaarthouder wordt automatisch doorgestuurd naar zijn/haar uitgevende bank voor authenticatie.
5. De kaarthouder identificeert zich. Ons systeem ontvangt het resultaat van de uitgever.
6. Afhankelijk van het resultaat, zijn er twee scenario's mogelijk.
   
   • Als de identificatie niet geslaagd is, sturen we de kaarthouder door naar de DECLINEURL, en wordt de flow beëindigd. Je ontvangt het resultaat via Gehoste betaalpagina -feedbackkanalen.
   • Als de identificatie geslaagd is, verzenden we de werkelijke financiële transactie naar de accepteerder om de transactie te verwerken.
7. Wij bezorgen je het resultaat van de betaling. Afhankelijk van het resultaat van de accepteerder, sturen we de kaarthouder door naar een van de volgende URL's: ACCEPTURL / DECLINEURL / EXCEPTIONURL. Je ontvangt het resultaat via Gehoste betaalpagina-feedbackkanalen.
8. Als de transactie geslaagd is, kun je de goederen/diensten leveren.

This graph describes the DIRECTLINK (DPR/D3D) + Fraud transaction flow

Of er overdracht van aansprakelijkheid is, hangt af van uw overeenkomst met uw acquirer. Wij raden u dan ook aan om de voorwaarden te controleren bij uw acquirer.

9.2 3-D Secure v2-verzoek verzenden

Om transacties met 3-D Secure te verwerken, stuur je een set van verplichte, aanbevolen en optionele parameters naar ons platform.

Deze parameters moeten in de SHA-IN worden opgenomen.

Parameters vastleggen en verzenden

Je moet de 3DS-specifieke verplichte/aanbevolen/optionele parameters vastleggen op je betalingspagina.

Hier vind je een Javascript codeblok dat je kunt gebruiken om de browserinformatie vast te leggen.

<script type="text/javascript" language="javascript">
function createHiddenInput(form, name, value)
{
var input = document.createElement("input");
input.setAttribute("type", "hidden");
input.setAttribute("name", name);
input.setAttribute("value", value);
form.appendChild(input);
}

var myCCForms = document.getElementsByName("MyForm");
if (myCCForms != null && myCCForms.length > 0)
{
var myCCForm = myCCForms[0];
createHiddenInput(myCCForm, "browserColorDepth", screen.colorDepth);
createHiddenInput(myCCForm, "browserJavaEnabled", navigator.javaEnabled());
createHiddenInput(myCCForm, "browserLanguage", navigator.language);
createHiddenInput(myCCForm, "browserScreenHeight", screen.height);
createHiddenInput(myCCForm, "browserScreenWidth", screen.width);
createHiddenInput(myCCForm, "browserTimeZone", new Date().getTimezoneOffset());
}
</script>

Verzend deze 3-D Secure-specifieke parameters samen met de andere verplichte DirectLink-parameters. Ons platform zal je verzoek verwerken en je een respons bezorgen.

Geweigerde transacties begrijpen

PSD2 verhoogt de transparantie van het betalingsproces voor jou en je klanten. Dit is vooral nuttig bij status 2-transacties.
Onze feedbackparameter CH_AUTHENTICATION_INFO geeft je gedetailleerde informatie van de uitgevers wanneer zij transacties van je klanten weigeren. Deel deze informatie met je klanten zodat ze begrijpen waarom hun bank de transactie heeft geweigerd. De informatie kan je misschien ook helpen om de transactie te herstellen door middel van onze Soft Decline-functionaliteit.

Om zowel in de XML-respons als in je doorverwijzings-URL's de CH_AUTHENTICATION_INFO te krijgen, selecteer je deze parameter in de Back Office via Configuratie > Technische instellingen > Transactiefeedback > Dynamische e-Commerce parameters en DirectLinks > Dynamische parameters respectievelijk. Dit zorgt er ook voor dat deze informatie zichtbaar is in het transactieoverzicht via Transacties > Beheer transacties / Financiële historiek.

Gebruik CH_AUTHENTICATION_INFO voor een van de volgende mogelijke scenario's:

• Als de transactie via de vlotte authenticatie gaat, zal onze XML-respons deze parameter bevatten. Voeg de informatie dan zo toe aan de resultatenpagina van de transactie
• Als de transactie via de challenge flow gaat, krijg je deze parameter via Gehoste betaalpagina-feedbackkanalen. Aangezien je de informatie niet op tijd krijgt om je doorverwijzings-URL's aan te passen nadat een transactie is afgerond, raden we je aan "Ik wil dat Worldline een kort redirectiebericht toont aan de klant voordat deze wordt teruggestuurd naar mijn website." in te schakelen in de Back Office via Configuratie > Technische instellingen > Transactiefeedback > eCommerce > HTTP redirectie in de browser. Ons platform verwijst je klanten dan door naar onze resultatentussenpagina met de informatie, voordat ze uiteindelijk op je doorverwijzings-URL's terechtkomen.

Platform-respons verwerken

Als de transactie via de wrijvingsloze flow gebeurt, bevat de respons de standaard parameters met de laatste transactiefeedback. Hiermee eindigt de flow.

Als de transactie via de challenge-flow gebeurt, bevat de respons aanvullende parameters. Om de authenticatie naar je klanten uit te rollen, moet je de aanvullende gegevens die je krijgt als volgt verwerken:

Veld	Beschrijving
STATUS	Nieuwe waarde: "46" (wachten op identificatie)
HTML_ANSWER	BASE64-gecodeerde html-code moet worden toegevoegd aan de html-pagina die de klant terugkrijgt. Deze tag wordt toegevoegd als een child-tag van de <ncresponse> globale XML-tag. Het veld HTML_ANSWER bevat html-code die moet worden toegevoegd aan de html-pagina die de browser van de klant terugkrijgt. Deze code zal de identificatiepagina van de uitgevende bank automatisch laden in een pop-up in het hoofdvenster, afhankelijk van de waarde van de WIN3DS-parameter. Om storingen te voorkomen tussen de html-tags die worden opgenomen in de inhoud van de HTML_ANSWER XML-tag, wordt de inhoud van HTML_ANSWER door ons systeem BASE64-gecodeerd voordat de respons wordt teruggestuurd. De rest van de XML wordt teruggestuurd als een respons op het DirectLink-verzoek. Bijgevolg moet de inhoud van HTML_ANSWER BASE64-geDEcodeerd worden voordat deze wordt opgenomen in de html-pagina die naar de kaarthouder wordt gestuurd.

Als de identificatie niet geslaagd is, sturen we de kaarthouder door naar de DECLINEURL, en wordt de flow beëindigd. Je ontvangt het resultaat via Gehoste betaalpagina-feedbackkanalen.

Als de identificatie geslaagd is, verzenden we de werkelijke financiële transactie naar de accepteerder.

Afhankelijk van het resultaat van de accepteerder, sturen we de kaarthouder door naar een van de volgende URL's: ACCEPTURL / DECLINEURL / EXCEPTIONURL. Je ontvangt het resultaat via Gehoste betaalpagina-feedbackkanalen.

9.3 Testkaarten

Met de volgende testkaart kunt u een 3-D Secure-geregistreerde kaart simuleren in onze testomgeving:

Vlotte authenticatie
Merk	Kaartnummer	Vervaldatum
VISA	4186455175836497	Willekeurige datum in de toekomst
Mastercard	5137009801943438	Willekeurige datum in de toekomst
American Express	375418081197346	Willekeurige datum in de toekomst
Carte Bancaire	4150557357382737	Willekeurige datum in de toekomst

Authenticatie met challenge
Merk	Kaartnummer	Vervaldatum
VISA	4874970686672022	Willekeurige datum in de toekomst
Mastercard	5130257474533310	Willekeurige datum in de toekomst
American Express	379764422997381	Willekeurige datum in de toekomst
Carte Bancaire	4150550997933993	Willekeurige datum in de toekomst

Opmerking: u kunt hier meer testkaarten downloaden. Als een transactie wordt geblokkeerd wegens foutieve identificatie is het transactieresultaat: STATUS = 2 NCERROR = 40001134

9.4 Uitsluitingen van de 3DSv2-regel

Sommige transacties zijn uitgesloten van SCA. Als een of meer van jouw transacties hieronder vallen, wordt 3-D Secure niet geïmplementeerd. Raadpleeg onze gedetailleerde handleiding hier voor meer informatie over de types transacties waar dit voor geldt.

Je kunt op twee manieren vragen 3-D Secure niet toe te passen

1. Authenticatie door selectie van de juiste waarden voor Mpi.threeDSRequestorChallengeIndicator en 3DS_EXEMPTION_INDICATOR
   

   Parameter	Waarden
   Mpi.threeDSRequestorChallengeIndicator	Lengte: 2 tekens Gegevenstype: tekenreeks Geaccepteerde waarden: 01 = Geen voorkeur 02 = Er wordt niet om een challenge gevraagd - gebruik deze waarde voor transacties met een laag bedrag (minder dan 30 euro) 03 = Er wordt om een challenge gevraagd: voorkeur handelaar 04 = Er wordt om een challenge gevraagd: Verordening - gebruik deze waarde wanneer je een terugkerende transactie met je klant instelt of wanneer je de transactie opnieuw probeert na een soft decline (zachte weigering) 05 = Er wordt niet om een challenge gevraagd [er is al een risicoanalyse voor de transactie uitgevoerd]. Gebruik deze waarde als jouw verwerver TRA-uitzonderingen met je is overeengekomen. 07 = Er wordt niet om een challenge gevraagd [SCA is al uitgevoerd]. Gebruik deze waarde wanneer je de SCA aan jouw kant uitvoert; moet zijn goedgekeurd door jouw verwerver
   3DS_EXEMPTION_INDICATOR	Lengte: 2 tekens Gegevenstype: tekenreeks Geaccepteerde waarden: 03 = TRA* uitgever 04 = Uitzondering laag bedrag 05 = TRA* handelaar/verwerver 06 = Whitelisting 07 = Bedrijf 08 = Vertraagde verzending 09 = Gedelegeerde authenticatie (gecertificeerde wallet) * Transaction risk analysis

   Controleer het authenticatielogboek in Back Office en zoek naar "TransStatus = I" om te zien of de uitgever de uitzondering heeft verleend. Indien een transactie frauduleus blijkt te zijn, kun je echter geen beroep doen op de aansprakelijkheidsverschuiving

2. Autorisatie door selectie van de juiste 3DS-EXEMPTION en FLAG3D
   Verstuur de volgende parameters om 3-D Secure helemaal over te slaan:
   

   Parameter	Waarden
   FLAG3D	N = het 3DS-authenticatieproces overslaan
   3DS_EXEMPTION_INDICATOR	Lengte: 2 tekens Gegevenstype: tekenreeks Geaccepteerde waarden: 03 = TRA* uitgever 04 = Uitzondering laag bedrag 05 = TRA* handelaar/verwerver 06 = Whitelisting 07 = Bedrijf 08 = Vertraagde verzending 09 = Gedelegeerde authenticatie (gecertificeerde wallet) * Transaction risk analysis

   
   Het blijft echter aan de uitgever of een authenticatieproces moet worden doorlopen. Indien de uitgever 3DS eist, zal de transactie worden afgewezen met foutcode 40001139.
   Als de transactie wordt geaccepteerd zonder 3-D Secure, verlies je jouw aansprakelijkheidsbescherming.
   
   
   Wanneer jouw klanten een nieuwe terugkerende betaling bij je instellen, moet onder de PSD2-regels altijd sterke authenticatie worden gebruikt voor de eerste transactie. Verzend alle relevante 3DS-parameters, COF-parameters tezamen met Mpi.threeDSRequestorChallengeIndicator=04. Dit zorgt ervoor dat de uitgever zich bewust is van dit verzoek en dat deze de transactie zal goedkeuren

Wrijvingsloze/Controlestroom

Als je geen vrijstelling wilt aanvragen maar vertrouwt op het door de uitgever implementeren van een wrijvingsloze stroom en de aansprakelijkheidsbescherming houdt, moet je een paar extra parameters verzenden.
Door deze parameters te verzenden voor deze netwerken, verhoog je de kans op een wrijvingsloze stroom.

• Carte Bancaire (als je deelneemt aan het laag-risicoprogramma voor handelaren, wordt dit sterk aangeraden)
  ECOM_BILLTO_POSTAL_CITY
  ECOM_BILLTO_POSTAL_COUNTRYCODE
  ECOM_BILLTO_POSTAL_STREET_LINE1
  ECOM_BILLTO_POSTAL_POSTALCODE
  EMAIL
  OWNERTELNO
  Mpi.shippingIndicator
  REMOTE_ADDR
  
  
• MasterCard
  ECOM_BILLTO_POSTAL_CITY
  ECOM_BILLTO_POSTAL_COUNTRYCODE
  ECOM_BILLTO_POSTAL_STREET_LINE1
  ECOM_BILLTO_POSTAL_POSTALCODE
  EMAIL
  OWNERTELNO
  ADDMATCH
  REMOTE_ADDR

Je kunt zelfs de kans op een wrijvingsloze flow en een hoger conversiepercentage verhogen door meer optionele parameters te versturen.

Soft Decline

Een typische flow voor een dergelijke transactie met Soft Decline ziet er als volgt uit

1. Je stuurt in je eerste verzoek FLAG3D=N en de geschikte waarde voor parameter 3DS_EXEMPTION_INDICATOR zonder verdere authenticatieparameters. Je geeft zo aan dat je 3-D Secure wilt overslaan. Het is mogelijk dat de transactie op dit punt wordt geaccepteerd.
   Als de transactie echter wordt geweigerd door de bank van je klant, omdat deze erop staat dat 3-D Secure wordt gebruikt, geven we dit aan in de feedbackparameter door NCERROR=40001139 te verzenden. De transactie wordt in status 2
2. Je kunt deze geweigerde transactie herstellen door deze opnieuw te verzenden door de volgende parameters naar ons platform te sturen
   1. De e-Commerce / DirectLink parameters zoals deze worden verzonden in je eerste verzoek als een nieuwe eCommerce- of DirectLink-order
   2. FLAG3D=Y om aan te geven dat 3-D Secure moet worden geïmplementeerd
   3. De 3DSv2-authenticatieparameters as described here
   4. Mpi.threeDSRequestorChallengeIndicator=04 om aan te geven dat de bank van je klant 3-D Secure vereist na de Soft Decline

Je klant moet tijdens dit tweede verzoek met goed gevolg door de 3-D Secure-authenticatie heenkomen. Als laatste bereikt de transactie status 2 of 9. Dit hangt er vanaf of je klant de authenticatie doorstaat en de betaling door zowel jou als de bank van je klant wordt geaccepteerd

Soft Decline  is momenteel beschikbaar voor de betalingsmethoden Visa, MasterCard, American Express en Carte Bancaire.

9.5 Migratie van v2.1 naar v2.2

De aankomende nieuwe versie van 3-D Secure (v2.2) zal je nog meer mogelijkheden bieden voor het optimaliseren van jouw integratie.

Parameter

Waarden

BROWSERJAVASCRIPTENABLED Deze booleaanse waarde geeft aan of bij jouw klanten JavaScript is ingeschakeld in hun browsers als ze een aankoop doen. Afhankelijk van de waarde is het volgende van toepassing TRUE: de volgende parameters blijven verplicht: BROWSERJAVAENABLED BROWSERSCREENHEIGHT BROWSERSCREENWIDTH BROWSERTIMEZONE BROWSERACCEPTHEADER BROWSERUSERAGENT BROWSERLANGUAGE FALSE: de volgende parameters zijn niet meer verplicht: BROWSERCOLORDEPTH BROWSERJAVAENABLED BROWSERSCREENHEIGHT BROWSERSCREENWIDTH BROWSERTIMEZONE Deze parameter blijft verplicht: BROWSERACCEPTHEADER BROWSERUSERAGENT BROWSERLANGUAGE

Gegevenstype: Boolean Geaccepteerde waarden: TRUE FALSE Als je deze parameter niet verzendt, vullen we deze waarde automatisch voor je in, afhankelijk van de andere beschikbare parameters.

9.6 DirectLink 3-D Secure-transactiestroom v1.0 (verouderd)

Om transacties met 3-D Secure te verwerken, verstuur je een set van verplichte en optionele parameters naar ons platform.

In de tabel vind je een overzicht van de verschillende parameters en hun functies voor het authenticatieproces.

Deze parameters moeten in de SHA-IN worden opgenomen.

Parameter category	Parameter	Naam / Beschrijving
Verplichte	FLAG3D	Vaste waarde: "Y" Geeft ons systeem de opdracht om 3-D Secure-identificatie uit te voeren indien nodig.
	HTTP_ACCEPT*	Deze parameter is vervangen door browserAcceptHeader. Verstuur deze niet als je de volgende al verstuurt browserAcceptHeader. Het veld Accept in de verzoekheader in de browser van de kaarthouder wordt gebruikt om bepaalde mediatypes te specificeren die aanvaard worden voor het antwoord. Deze waarde wordt gebruikt door de uitgever om na te gaan of de browser van de kaarthouder compatibel is met het identificatiesysteem van de uitgever. Bijvoorbeeld: Accept: */*
	HTTP_USER_AGENT*	Het veld User-Agent in de verzoekheader in de browser van de kaarthouder bevat informatie over de agent van de gebruiker van wie het verzoek uitgaat. Deze waarde wordt gebruikt door de uitgever om na te gaan of de browser van de kaarthouder compatibel is met het identificatiesysteem van de uitgever. Bijvoorbeeld: User-Agent: Mozilla/4.0 (compatibel; MSIE 6.0; Windows NT 5.0)
	ACCEPTURL	De URL van de webpagina die aan de klant wordt getoond als de betaling werd geautoriseerd (of wacht op autorisatie).
	DECLINEURL	De URL naar waar de klant wordt doorgestuurd wanneer het maximale aantal mislukte autorisatiepogingen is bereikt (standaard 10, maar kan worden gewijzigd op de pagina ‘Technical Information’ (Technische informatie), in de sectie ‘Payment retry’ (Betaalpogingen) van het tabblad ‘Global transaction parameters’ (Algemene transactieparameters).
	EXCEPTIONURL	De URL van de webpagina die aan de klant wordt getoond als het resultaat van de betaling onzeker is.
	LANGUAGE	De standaardtaal wordt gebruikt als er geen taalwaarde of een ongeldige taalwaarde wordt verzonden: en_US (Engels)
Optionele	TP	Om de opmaak van de pagina ‘order_A3DS’ te wijzigen, kunt u via deze parameter de naam of URL van een template versturen (ga naar e-Commerce: Dynamische sjabloon).
	PARAMPLUS	Field to submit the miscellaneous parameters and their values that you wish to be returned in the post-sale request or final redirection.
	COMPLUS	Field to submit a value you wish to be returned in the post-sale request or output.
	WIN3DS	Hoe de identificatiepagina aan de klant wordt getoond. Mogelijke waarden: MAINW: om de identificatiepagina in het hoofdvenster weer te geven (standaardwaarde). POPUP: om de identificatiepagina weer te geven in een pop-upvenster en nadien terug te keren naar het hoofdvenster. POPIX: om de identificatiepagina weer te geven in een pop-upvenster en nadien in het pop-upvenster te blijven.

Nadat deze parameters zijn verzonden, zal ons platform je verzoek verwerken en je een respons bezorgen.

Platform-respons verwerken

Als de kaart van je klant niet is geregistreerd voor 3-D Secure, bevat de respons de standaard parameters met de laatste transactiefeedback. Hiermee eindigt de flow.

Als de kaart van je klant wel is geregistreerd voor 3-D Secure, bevat de respons aanvullende parameters. Om de authenticatie naar je klanten uit te rollen, moet je de aanvullende gegevens die je krijgt als volgt verwerken:

Veld	Beschrijving
STATUS	Nieuwe waarde: "46" (wacht op identificatie).
HTML_ANSWER	HTML-code in BASE64-codering die moet worden toegevoegd aan de HTML-pagina die wordt teruggestuurd naar de klant. Deze tag wordt toegevoegd als subtag van de algemene XML-tag <ncresponse>. Het veld HTML_Answer bevat HTML-code die moet worden toegevoegd aan de HTML-pagina die wordt teruggestuurd naar de browser van de klant. Deze code laadt automatisch de identificatiepagina van de uitgevende bank in een pop-upvenster of in het hoofdvenster, naargelang de waarde van parameter WIN3DS. Om te voorkomen dat de HTML-tags in de inhoud van de XML-tag HTML_ANSWER interfereren met de rest van de XML die wordt teruggestuurd als antwoord op het DirectLink-verzoek, wordt de inhoud van HTML_ANSWER door ons systeem BASE64-gecodeerd voordat het antwoord wordt teruggestuurd. Die inhoud moet bijgevolg BASE64-geDEcodeerd worden voor hij wordt toegevoegd aan de HTML-pagina die naar de kaarthouder wordt gestuurd.

Als de identificatie niet geslaagd is, sturen we de kaarthouder door naar de DECLINEURL, en wordt de flow beëindigd. Je ontvangt het resultaat via Gehoste betaalpagina-feedbackkanalen.

Als de identificatie geslaagd is, verzenden we de werkelijke financiële transactie naar de accepteerder.

Afhankelijk van het resultaat van de accepteerder, sturen we de kaarthouder door naar een van de volgende URL's: ACCEPTURL / DECLINEURL / EXCEPTIONURL. Je ontvangt het resultaat via Gehoste betaalpagina-feedbackkanalen.

Testkaarten

Met de volgende testkaarten kunt u een 3-D Secure-geregistreerde kaart simuleren in onze testomgeving:

Merk	Kaartnummer	Vervaldatum	Wachtwoord
VISA	4000000000000002	Willekeurige datum in de toekomst	11111
MasterCard	5300000000000006	Willekeurige datum in de toekomst	11111
American Express	371449635311004	Willekeurige datum in de toekomst	11111

Opmerking: u kunt hier meer testkaarten downloaden. Als een transactie wordt geblokkeerd wegens foutieve identificatie is het transactieresultaat: STATUS = 2 NCERROR = 40001134

9.7 Een overzicht krijgen van 3-D Secure-transacties

We bieden je een manier om je 3DS-rapport te openen in Back Office zodat je jouw transacties en hun 3-D Secure-resultaten kunt volgen.

In deze video wordt uitgelegd hoe je jouw rapport snel en makkelijk kunt instellen.