1 Algemene procedures en veiligheidsinstellingen
   1.1 API-gebruiker
   1.2 Verzoekformulier
   1.3 Veiligheid
      1.3.1 Versleuteling
      1.3.2 IP-adres
      1.3.3 SHA-handtekening
   1.4 Verwerking van het antwoord
2 Een nieuw bestellingsverzoek indienen
   2.1 Verzoek-URL
   2.2 Verzoekparameters
   2.3 Testpagina
   2.4 Specifieke betaalmethoden uitsluiten
   2.5 Bestellingsverzoek met behulp van 3-D Secure
   2.6 Credit-/debitcards splitsen
   2.7 Transacties met opgeslagen referenties verwerken
3 Antwoord op een bestelling
   3.1 Dubbel verzoek
4 Rechtstreeks onderhoud
   4.1 Onderhoudsverzoek
      4.1.1 Verzoek-URL
      4.1.2 Verzoekparameters
      4.1.3 Testpagina
   4.2 Antwoord op een onderhoudsverzoek
   4.3 Dubbel verzoek
5 Rechtstreekse opvraging
   5.1 Opvragingsverzoek
      5.1.1 Verzoek-URL
      5.1.2 Verzoekparameters
      5.1.3 Testpagina
   5.2 Antwoord op een opvraging
      5.2.1 Transacties verwerkt met e-Commerce (gehoste betaalpagina)
   5.3 Mogelijke antwoordstatussen
   5.4 Rechtstreekse opvraging als controle
6 Privacymeldingverzoek verwerkingsverantwoordelijke
   6.1 Informeer hoe privacygegevens van een klant wordt verwerkt
      6.1.1 Verzoek-URL
      6.1.2 Verzoekparameters
      6.1.3 Testpagina
   6.2 Antwoord op een opvraging
7 Uitzonderingen voor betaalmethoden
   7.1 Automatische incasso
      7.1.1 Automatische incasso Oostenrijk
      7.1.2 Automatische incasso Duitsland (ELV)
      7.1.3 Automatische incasso Nederland
   7.2 Betaalmethoden met alleen onderhoud via DirectLink
8 3-D Secure v1.0
   8.1 Inleiding
   8.2 3-D-transactieverloop via DirectLink
      8.2.1 Bijkomende verzoekparameters
      8.2.2 Bijkomende retourvelden
      8.2.3 Opmerkingen
9 3-D Secure v2.1
   9.1 Introduction
   9.2 3-D-transactieverloop via DirectLink
      9.2.1 Bijkomende verzoekparameters
      9.2.2 Bijkomende retourvelden
      9.2.3 3-D Secure v2.1 MasterCard+
      9.2.4 Opmerkingen
   9.3 Uitsluitingen en uitzonderingen voor 3DsV2
      9.3.1 3DSv2 en uitsluitingen
      9.3.2 Wrijvingsloos proces / identificatiecontroleproces SCA en 3DS
      9.3.3 Indicatie van het voorkeursproces
      9.3.4 Uitzonderingen bij 3DS

1 Algemene procedures en veiligheidsinstellingen

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

1.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 Ingenico ePayments-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.

Een API-gebruiker aanmaken

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).

1.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.

1.3 Veiligheid

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

1.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.

1.3.2 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 Ingenico ePayments 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.

1.3.3 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 (Ingenico ePayments e-Commerce-documentatie) - het principe is identiek in e-Commerce- en DirectLink-modus.

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

1.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.

2 Een nieuw bestellingsverzoek indienen

2.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.

2.2 Verzoekparameters

2.3 Testpagina

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

2.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.

2.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.

2.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 Ingenico ePayments-account kunt u de functie 'splitsen' ook activeren en configureren per betaalmethode. Ga naar Split credit/debit cards voor meer informatie.

2.7 Transacties met opgeslagen referenties verwerken

Transacties met bewaarde referenties (BR) gebruiken bestaande kaartgegevens die reeds opgeslagen zijn door merchants om de betaling te verwerken. Alvorens een transactie met bewaarde referenties (BR) uit te voeren, moet de kaarthouder toestemming geven aan de merchant om de kaartgegevens op te slaan. Bewaarde referenties (BR) worden meestal gebruikt voor terugkerende betalingen en geven aan of de betaling uitgevoerd wordt door een kaarthouder of een merchant.

Er zijn twee soorten transacties met bewaarde referenties (BR): transacties uitgevoerd door de kaarthouder (TUK) en transacties uitgevoerd door de merchant (TUM). Transacties uitgevoerd dor de kaarthouder (TUK) moeten altijd voor transacties uitgevoerd door de merchant (TUM) gebeuren.

Een transactie uitgevoerd door de kaarthouder (TUK) is een transactie waarbij de kaarthouder betrokken is en die hij/zij persoonlijk verifieert door middel van een handtekening, het toepassen van 3D-Secure of door zich te identificeren.

Voorbeeld van een transactie uitgevoerd door de kaarthouder (TUK):

Een kaarthouder koopt een online treinkaartje en doet een betaling. Hij/zij doet de betaling met zijn/haar kredietkaart en wordt gevraagd om de betaling te verifiëren en toe te staan. Er wordt op dat moment ook gevraagd of de kaarthouder de gegevens van de kredietkaart voor die betaling wil opslaan. Als de kaarthouder hiermee akkoord gaat, kunnen die gegevens opnieuw gebruikt worden in toekomstige transacties uitgevoerd door de merchant.

Een transactie uitgevoerd door de merchant (TUM) volgt op een transactie uitgevoerd door de kaarthouder (TUK) en op een vooraf overeengekomen doorlopende opdracht voor goederen en diensten die de kaarthouder koopt. De kaarthouder hoeft niet betrokken te zijn bij deze transactie.

Voorbeeld van een transactie uitgevoerd door de merchant (TUM):

Een merchant kan automatisch een transactie uitvoeren zodat de kaarthouder voldoet aan zijn/haar maandelijkse betaling voor een tijdschriftabonnement.

In overeenstemming met de regelgeving van Visa en MasterCard omtrent transacties met bewaarde referenties (TBR), moeten er nieuwe parameters verstuurd worden om de TBR te bepalen.

Deze zijn van toepassing als u:

  • een alias gebruikt
  • van plan bent om terugkerende transacties uit te voeren (gepland of ongepland) na uw eerste transactie uitgevoerd door de kaarthouder (TUK)

Vereiste handeling

Deze parameters worden standaard gebruikt bij een e-Commerce-transactie:

Parameterwaarden COF_INITIATOR-COF_TRANSACTION-COF_SCHEDULE

Omschrijving

CIT-FIRST-UNSCHED
Van toepassing wanneer er een alias gebruikt of aangemaakt wordt
CIT-FIRST-SCHED

Van toepassing op een eerste geplande betaling/abonnement

MIT-SUBSEQ-UNSCHEDULED Van toepassing op terugkerende betalingen
MIT-SUBSEQ-SCHEDULED Van toepassing op afbetalingen

De standaardwaarden worden opgegeven als u geen parameters toevoegt. Als u wilt, kunt u dit veranderen en de standaardwaarden vervangen door de nieuwe parameters te versturen. Vergeet niet om ook de SHA-handtekening te herberekenen (klik hier voor meer informatie over de SHA-handtekening)

Veld

Waarden

Beschrijving

COF_INITIATOR CIT Een transactie uitgevoerd door een kaarthouder
MIT Een transactie uitgevoerd door een merchant
COF_SCHEDULE
SCHED Een geplande transactie
UNSCHED Een ongeplande transactie
COF_TRANSACTION
FIRST De eerste van een reeks transacties

SUBSEQ

Opeenvolgende reeks transacties

COF_RECURRING_EXPIRY Datum JJJJMMDD (bijv. 20190914) Einddatum: datum van de laatste geplande betaling van een reeks
COF_RECURRING_FREQUENCY numeriek tussen 2 en 4 karakters (bijv. 31, 031 of 0031) Dagen tussen betalingen voor een geplande reeks

3 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.

3.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”.

4 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.

4.1 Onderhoudsverzoek

4.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.

4.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.

4.1.3 Testpagina

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

4.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.

4.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.

5 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).

5.1 Opvragingsverzoek

5.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.

5.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.

5.1.3 Testpagina

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

5.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.

5.2.1 Transacties verwerkt met e-Commerce (gehoste betaalpagina)

Als de transactie waarvan u de status wilt controleren werd verwerkt met e-Commerce (gehoste betaalpagina), ontvangt u mogelijk ook de volgende extra attributen (op voorwaarde dat u die velden hebt meegestuurd bij de oorspronkelijke e-Commerce-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 (e-Commerce-documentatie).

Voorbeeld van een XML-antwoord op een rechtstreekse opvraging voor een e-Commerce-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"/>

5.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:

StatusNCERRORNCSTATUS Omschrijving
88 De opvraging op querydirect.asp is mislukt

5.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.

6 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.

6.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
• De verzoek-URL in de PRODUCTIE-omgeving is https://secure.ogone.com/ncol/prod/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

6.1.1 Verzoek-URL

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

• De verzoek-URL in de PRODUCTIE-omgeving is https://secure.ogone.com/ncol/prod/privacy-policy.asp
Vervang "test" door "prod"
Vervang "test" door "prod" in de verzoek-URL wanneer u overstapt op uw productie-account.

6.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.

6.1.3 Testpagina

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

6.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>

2. Voorbeeld van een XML-antwoord voor succes met inhoud. Het voorbeeld geeft een weergave met 2 secties aan.

<?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>

7 Uitzonderingen voor betaalmethoden

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

7.1 Automatische incasso

7.1.1 Automatische incasso Oostenrijk

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

Formaat: AN = alfanumeriek / N = numeriek, maximaal aantal toegelaten tekens
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)

7.1.2 Automatische incasso Duitsland (ELV)

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

Formaat: AN = alfanumeriek / N = numeriek, maximaal aantal toegelaten tekens
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)

7.1.3 Automatische incasso Nederland

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

Formaat: AN = alfanumeriek / N = numeriek, maximaal aantal toegelaten tekens
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).

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.

8 3-D Secure v1.0

8.1 Inleiding

Met het 3-D Secure-protocol kan de kaarthouder geïdentificeerd worden tijdens het aankoopproces. De kaarthouder moet tijdens het identificatieproces met het internet verbonden zijn. 3-D Secure werkt dan ook niet voor betalingen via callcenters of periodieke betalingen.

Visa implementeerde het 3-D Secure-protocol onder de naam Verified By Visa, MasterCard onder de naam SecureCode, JCB onder de naam J-Secure en American Express onder de naam SafeKey.

Het principe achter de integratie van DirectLink met 3-D Secure is dat de betaling wordt gestart in DirectLink-modus en wordt voltooid in e-Commerce-modus indien om authenticatie van de kaarthouder wordt verzocht.

Dit document beschrijft de integratie van het 3-D Secure-protocol in DirectLink. Meer informatie over DirectLink en e-Commerce vindt u in de documentatie over DirectLink en e-Commerce.

De transactie verloopt volgens onderstaande stappen:

  1. U stuurt ons een DirectLink-verzoek voor de transactie, dat enkele bijkomende parameters bevat (zie Bijkomende verzoekparameters).
  2. Ons systeem ontvangt het kaartnummer in uw verzoek en controleert online of de kaart is geregistreerd in de VISA/MasterCard/JCB/AmEx-directory (geregistreerd betekent dat voor dat kaartnummer identificatie mogelijk is, met andere woorden dat het om een 3-D Secure-kaart gaat).
  3. Als de kaarthouder geregistreerd is, bevat het antwoord op het DirectLink-verzoek een specifieke betalingsstatus en HTML-code die moet worden teruggestuurd naar de klant om het identificatieproces te starten (zie Bijkomende retourvelden). Het blok HTML-code start automatisch het identificatieproces tussen de kaarthouder (de klant) en de bank die zijn kaart heeft uitgegeven.
  4. De kaarthouder identificeert zich op de pagina van de uitgevende bank.
  5. Ons systeem ontvangt het identificatie-antwoord van de uitgever.
  6. Als de identificatie is geslaagd, stuurt ons systeem de eigenlijke financiële transactie naar de acquirer.
  7. U ontvangt het resultaat van het volledige identificatie- en online autorisatieproces via de feedbackkanalen in e-Commerce-modus.

Opmerkingen:

  • 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.
  • Als de kaarthouder niet geregistreerd is (in stap 3), ontvangt u het standaard DirectLink -XML-antwoord met het resultaat van het online autorisatieproces.
  • Om de precieze betalingsstatus/foutcodes te ontvangen (in stap 7), moet u de online of offline feedback na verkoop activeren zoals beschreven in de e-Commerce documentatie.

8.2.1 Bijkomende verzoekparameters

Behalve de standaard DirectLink-parameters moet u ook de volgende informatie versturen:

Veld Beschrijving
FLAG3D

Vaste waarde: "Y"

Geeft ons systeem de opdracht om 3-D Secure-identificatie uit te voeren indien nodig.
HTTP_ACCEPT 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)
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.
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.
PARAMPLUS Veld om de diverse parameters en hun waarden te versturen die u vermeld wilt zien in het verzoek na verkoop of de uiteindelijke doorverwijzing.
COMPLUS Veld om een waarde te versturen die u vermeld wilt zien in het verzoek na verkoop of de output.
LANGUAGE De taal van de klant, bijvoorbeeld: "en_US"
Optioneel
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).

Ga voor meer informatie naar Transactiefeedback.

8.2.2 Bijkomende retourvelden

Als de kaarthouder niet geregistreerd is, wordt het normale DirectLink-antwoord teruggestuurd. Als de kaarthouder geregistreerd is, worden volgende (bijkomende) velden teruggestuurd:

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.

8.2.3 Opmerkingen

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
Foutieve identificatie

Als een transactie wordt geblokkeerd wegens foutieve identificatie is het transactieresultaat:

STATUS = 0

NCSTATUS = 5

NCERROR = 40001134

9 3-D Secure v2.1

9.1 Introduction

In 2013 publiceerde de Europese Commissie een voorstel voor de herziene versie van de richtlijn betreffende betalingsdiensten, die PSD2 (Payment Services Directive) wordt genoemd. Hiermee werd de verwerking van betalingen vereenvoudigd en werden de regels en voorschriften inzake betalingsdiensten in de EU ingevoerd. Zo ontstond de behoefte aan een nieuwe versie van 3-D Secure; v2.1.

De grootste verandering is dat u als merchant wordt gevraagd om meer gegevens te delen: uitgevers hebben gegevenspunten nodig zodat ze een nauwkeurige beslissing kunnen nemen, wat uiteindelijk leidt naar een vlotte afhandeling. Maar u bent degene die de eigenlijke gegevens verzamelt. Met 3DS v2 wordt de risicobeoordeling doeltreffender uitgevoerd, maar daarvoor moet het hele systeem veranderen, zodat u de gegevens kunt doorgeven aan de uitgever.

Met de introductie van de nieuwe richtlijn, hebben de belangrijkste kaartsystemen van de gelegenheid gebruikt gemaakt om hun 3DS logo’s te vernieuwen. Gelieve U ervan te verzekeren dat U deze geüpdatete logo’s gebruikt bij de opzet van uw betalingspagina (Visa / Mastercard / JCB /… ).

9.2 3-D-transactieverloop via DirectLink

De transactie omvat de volgende stappen:

1. U stuurt ons een DirectLink-request voor de transactie met een aantal bijkomende parameters.

Deze parameters kunnen worden ingedeeld in drie groepen:>

a. Verplichte parameters die moeten worden vastgelegd op de betaalpagina waar de kaarthouder de kaartgegevens invoert.

ParameterBeschrijvingFormaatVerplicht
browserAcceptHeader

Exacte inhoud van de HTTP accept-headers zoals die van de browser van de kaarthouder naar de merchant verzonden werden. *

Datatype: String
Lengte: Veranderlijk, max. 2048 tekens
Geaccepteerde waarde: Als de totale lengte van de accept-header die vanuit de browser werd verzonden groter is dan 2048 tekens, dan kort 3DS Server het overige deel in.
Ja
browserColorDepth Waarde die de bitdiepte aanduidt van het kleurenpalet dat afbeeldingen weergeeft, in bits per pixel. Verkregen van de browser van de kaarthouder door middel van de kleurdiepte-eigenschap. Datatype: String
Geaccepteerde waarden:
1 = 1 bit
4 = 4 bits
8 = 8 bits
15 = 15 bits
16 = 16 bits
24 = 24 bits
32 = 32 bits
48 = 48 bits
Ja
browserJavaEnabled Boolean die aanduidt of de browser van de kaarthouder Java kan uitvoeren. Waarde wordt teruggezonden vanuit de eigenschap "navigator javaEnabled". Datatype: Boolean
Geaccepteerde waarden:
true
false
Ja
browserLanguage Waarde die de taal van de browser aanduidt zoals gedefinieerd wordt in IETF BCP47. Teruggezonden vanuit de eigenschap "navigatortaal". Datatype: String
Lengte: Veranderlijk, 1-8 tekens
Ja
browserScreenHeight Totale hoogte van het scherm van de kaarthouder in pixels. Waarde wordt teruggezonden vanuit de eigenschap "schermhoogte". Datatype: Int
Tussen 0 en 999999
Ja
browserScreenWidth Totale breedte van het scherm van de kaarthouder in pixels. Waarde wordt teruggezonden vanuit de eigenschap "schermbreedte". Datatype: Int
Tussen 0 en 999999
Ja
browserTimeZone Tijdsverschil tussen UTC-tijd en de lokale tijd van de browser van de kaarthouder, in minuten. Datatype: Int
Tussen -840 en 720
Ja
browserUserAgent Exacte inhoud van de HTTP useragent header. * Datatype: String
Lengte: Veranderlijk, max. 2048 tekens
Opmerking: Als de totale lengte van de
useragent-header die vanuit de browser
werd verzonden groter is dan 2048 tekens,
dan kort 3DS Server het overige deel in.
Ja
CN Naam van de kaarthouder (klant) Lengte: Veranderlijk, max. 35
Speciale tekens zijn toegestaan, maar aanhalingstekens moeten vermeden worden. De meeste acquirers controleren de naam van de klant niet, aangezien namen op verschillende
manieren geschreven kunnen worden
Ja

* HTTP_ACCEPT en HTTP_USER_AGENT moeten niet worden verzonden met browsersAcceptHeader en browserUserAgent. Wij vullen deze met de browserparameters.

Opmerking: vergeet alsjeblieft niet om de parameters in je SHA-handtekening te berekenen.

U kan deze Javascript gebruiken om deze parameters te registreren.

<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>

b. Vereiste bijkomende parameters Bijkomende verzoekparameters).

c. Optionele bijkomende parameters (lijst met parameters) die, als ze worden opgestuurd, een positieve impact hebben op de conversie van de transacties. Afhankelijk van de informatie in deze parameters kan er mogelijk een vlotte authenticatie plaatsvinden, waarbij de kaarthouder zich niet meer moet authenticeren en zo de transactie sneller wordt afgerond. Als er echter geen van deze parameters worden doorgegeven, dan wordt de gebruikelijke omleiding voor de authenticatie uitgevoerd.

Alhoewel deze parameters optioneel zijn, wordt voor de belangrijkste kaartsystemen met klem aangeraden dat u de volgende parameters in uw aanvraag opneemt, aangezien dit de kans op een frictieloze flow verhoogt

ECOM_BILLTO_POSTAL_CITY
ECOM_BILLTO_POSTAL_COUNTRYCODE
ECOM_BILLTO_POSTAL_STREET_LINE1
ECOM_BILLTO_POSTAL_STREET_LINE2
ECOM_BILLTO_POSTAL_STREET_LINE3
ECOM_BILLTO_POSTAL_POSTALCODE
REMOTE_ADDR
CN
EMAIL

Ons systeem ontvangt het kaartnummer in uw verzoek en controleert online of de kaart is geregistreerd in de VISA/MasterCard/JCB/AmEx-directory (geregistreerd betekent dat voor dat kaartnummer identificatie mogelijk is, met andere woorden dat het om een 3-D Secure-kaart gaat).

2. Als de kaarthouder wordt geregistreerd, zijn er, afhankelijk van het antwoord van het programma en indien de bijkomende parameters van 1.c (Optionele bijkomende parameters-lijst met parameters) hierboven al dan niet werden doorgegeven (gegeven als de kaarthouder is geregistreerd voor 3-D Secure), twee soorten authenticatie mogelijk:

2.1. Een vlotte authenticatie: De kaarthouder hoeft zichzelf niet fysiek te authenticeren omdat de authenticatie op de achtergrond heeft plaatsgevonden zonder hun invoer. In dit geval is de schuldverschuiving bij de uitgevende bank.

2.2. Een authenticatie met challenge: De kaarthouder moet zich verder identificeren.

i. Het antwoord aan het DirectLink-request bevat een specifieke betaalstatus en een html-code die moet worden teruggestuurd naar de klant om het identificatieproces in gang te zetten (cf. Bijkomende retourvelden). De blok html-code zal het identificatieproces tussen de kaarthouder (klant) en zijn uitgevende bank automatisch in gang zetten.

ii. De kaarthouder identificeert zich op de pagina van de uitgevende bank.

iii. Ons systeem ontvangt het identificatie-antwoord van de uitgever.

iv. Als de identificatie is geslaagd, stuurt ons systeem de eigenlijke financiële transactie naar de acquirer.

3. U ontvangt het resultaat van het volledige identificatie- en online autorisatieproces via de feedbackkanalen in e-Commerce-modus.

9.2.1 Bijkomende verzoekparameters

Behalve de standaard DirectLink-parameters moet u ook de volgende informatie versturen:

Veld Beschrijving
FLAG3D

Vaste waarde: "Y"

Geeft ons systeem de opdracht om 3-D Secure-identificatie uit te voeren indien nodig.
HTTP_ACCEPT 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)
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.
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.
PARAMPLUS Veld om de diverse parameters en hun waarden te versturen die u vermeld wilt zien in het verzoek na verkoop of de uiteindelijke doorverwijzing.
COMPLUS Veld om een waarde te versturen die u vermeld wilt zien in het verzoek na verkoop of de output.
LANGUAGE De taal van de klant, bijvoorbeeld: "en_US"
Optioneel
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).

*HTTP_ACCEPT en HTTP_USER_AGENT moeten niet worden verzonden als browserAcceptHeader en browserUserAgent worden verzonden.

Ga voor meer informatie naar Transactiefeedback.

9.2.2 Bijkomende retourvelden

Als de kaarthouder niet geregistreerd is, wordt het normale DirectLink-antwoord teruggestuurd. Als de kaarthouder geregistreerd is, worden volgende (bijkomende) velden teruggestuurd:

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.

9.2.3 3-D Secure v2.1 MasterCard+

Ten einde de kans op een vlotte authenticatie te maximaliseren, heeft MasterCard de specifieke extensie "MasterCard 2.1+" ontwikkeld. Dit betekent dat je naast de aanbevolen parameters drie extra parameters kunt verzenden.

ParameterNaamBeschrijvingNotatie
Mpi.merchantFraudRate Percentage handelaarsfraude (Merchant Fraud) Het percentage handelaarsfraude in de EER (alle creditkaartfraude in de EER gedeeld door alle hoeveelheden creditcards in de EER) berekend volgens de technische reguleringsnormen voor PSD2 (Regulatory Technical Standards ofwel RTS).

Zorg ervoor dat je het percentage berekent volgens de regulering PSD2 RTS artikel 19, aangezien noch wij noch MasterCard de score zullen valideren.

Lengte: max. 2 tekens
Notatie: geheel getal 1=> 99
Geaccepteerde waarden:

  • 1 (geeft een fraudepercentage aan dat kleiner dan of gelijk is aan 1 basispunt [bp], wat gelijk staat aan 0,01%)
  • 2 (geeft een fraudepercentage aan dat tussen 1 bp + - en 6 bp's ligt)
  • 3 (geeft een fraudepercentage aan dat tussen 6 bps + - en 13 bp's ligt)
  • 4 (geeft een fraudepercentage aan dat tussen 13 bps + - en 25 bp's ligt)
  • 5 (geeft een fraudepercentage aan dat hoger is dan 25 bp's)

Mpi.secureCorporatePayment Veilige bedrijfsbetaling Geeft aan dat specifiek daartoe bestemde betalingsprocessen en -procedures zijn gebruikt en dat mogelijk de uitzondering voor veilige bedrijfsbetalingen van toepassing is.
Verzend dit veld alleen met "J" als het verwerversuitzonderingsveld leeg is, aangezien
verwerversuitzondering en veilige betaling elkaar wederzijds uitsluiten.
De directoryserver (DS) zal de voorwaarden in de extensie echter niet valideren. De DS zal de gegevens doorsturen zoals deze zijn ontvangen.
Je kunt optioneel aangeven dat deze van toepassing zijn op de speciaal daartoe bestemde processen en protocollen volgens PSD2 RTS artikel 17, wat de uitgever toe zou kunnen staan de uitzondering voor veilige bedrijfsbetalingen te claimen.

Lengte: max. 1 teken
Geaccepteerde notatie: booleaans
Geaccepteerde waarde:

  • Y
  • N
Mpi.threeDSRequestorChallengeIndicator Indicator challenge handelaar Geeft aan of je om een challenge vraagt voor deze transactie. Bijvoorbeeld:
Bij 01-PA heb je mogelijk bedenkingen over de transactie en vraag je om een challenge.
Bij 02-NPA kan een challenge nodig zijn wanneer een nieuwe kaart aan een wallet wordt toegevoegd.

Voor lokale/regionale verordeningen of andere variabelen.

Lengte: 2 tekens
Gegevenstype: tekenreeks
Geaccepteerde waarden:

  • 01 = Geen voorkeur
  • 02 = Er wordt niet om een challenge gevraagd
  • 03 = Er wordt om een challenge gevraagd: voorkeur handelaar
  • 04 = Er wordt om een challenge gevraagd: verordening
  • 05 = Er wordt niet om een challenge gevraagd [er is al een risicoanalyse voor de transactie uitgevoerd]
  • 06 = Er wordt niet om een challenge gevraagd [alleen gegevens delen]
  • 07 = Er wordt niet om een challenge gevraagd [SCA is aluitgevoerd]
  • 80-99 = Gereserveerd voor gebruik DS

Het verzenden van deze parameters zal alle betrokken partijen van veel meer informatie voorzien. Dit leidt niet alleen tot meer vlotte authenticaties, maar ook tot hogere goedkeuringspercentages en minder gevallen van fraude.
Houd in de gaten dat deze extra parameters alleen werken bij MasterCard-transacties. Het gebruik hiervan bij andere betalingsmethoden heeft geen enkel effect.

9.2.4 Opmerkingen

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

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

Opmerking: u kunt hier meer testkaarten downloaden.

Foutieve identificatie

Als een transactie wordt geblokkeerd wegens foutieve identificatie is het transactieresultaat:

STATUS = 0

NCSTATUS = 5

NCERROR = 40001134

9.3 Uitsluitingen en uitzonderingen voor 3DsV2

9.3.1 3DSv2 en uitsluitingen

Met de introductie van 3DSv2 zal authenticatie van kaarthouders over het algemeen verplicht worden, zoals gedefinieerd in de Herziene richtlijn betalingsdiensten (2015/2366 PSD2) van de EU. Sommige transacties zijn desondanks van deze regel uitgesloten indien een van de volgende scenario's van toepassing is:
  • Postorder / bestelling via telefoon
  • ‘One leg’-transacties - De PSP van de ontvanger (m.a.w. verwerver van de Handelaar) of de PSP van de betaler (m.a.w. verstrekker van de betalingsmethode van de Koper) ligt buiten de EER-zone
  • Anonieme prepaidkaarten tot maximaal €150 (artikel 63)
  • MIT - door de handelaar gestarte transacties

9.3.2 Wrijvingsloos proces / identificatiecontroleproces SCA en 3DS

Een deel van deze nieuwe reglementering is de Strong Customer Authentication (SCA) ofwel sterke klantenauthenticatie. Hieronder wordt het mogelijk dat de uitgever (de bank van de kaarthouder) aanvullende informatie zal vragen van de kaarthouder. In een dergelijk scenario zal het authenticatieproces resulteren in een identiteitscontroleproces (waarbij de kaarthouder zich actief moet authenticeren) in plaats van een wrijvingsloos proces (waarbij de kaarthouder zich niet hoeft te authenticeren).

We bieden onze handelaren echter de kans aan te geven aan welk proces ze de voorkeur geven. Dit kan worden bereikt door aanvullende parameters te verzenden die door de uitgever voor risicobeoordeling zullen worden gebruikt. Afhankelijk van het besluit van de uitgever kan een wrijvingsloos proces plaatsvinden. Bij sommige scenario's kan 3DS zelfs helemaal worden overgeslagen indien bepaalde uitzonderingen van toepassing zijn.

9.3.3 Indicatie van het voorkeursproces

De handelaar kan tijdens het authenticatieverzoek de aanvullende parameter Mpi.threeDSRequestorChallengeIndicator verzenden om de voorkeur voor een wrijvingsloos proces aan te geven. Afhankelijk van de beoordeling inzake frauderisico door de handelaar, kunnen specifieke waarden worden verzonden (m.a.w. 02 voor laag risico, 03 voor een verhoogd frauderisico).


Parameter Waarden Verplicht / optioneel
Mpi.threeDSRequestorChallengeIndicator 01 = Geen voorkeur
02 = Geen identiteitsbevestiging aangevraagd
03 = Identiteitsbevestiging aangevraagd: voorkeur van merchant
04 = Identiteitsbevestiging aangevraagd: Mandaat
Verplicht (als er een voorkeur is vorr een specifieke flow)

De handelaar kan de kans op een wrijvingsloos proces / conversieratio verhogen door meer optionele velden te verzenden.

9.3.4 Uitzonderingen bij 3DS

Voor sommige transacties kan de handelaar 3DS mogelijk overslaan (wat resulteert in een wrijvingsloos proces) en rechtstreeks naar de autorisatie gaan. Dit proces is alleen mogelijk voor transacties die van SCA zijn uitgesloten (zoals hierboven beschreven) of die gebruik kunnen maken van specifieke uitzonderingen. Deze uitzonderingen moeten deel uitmaken van een overeenkomst tussen de handelaar en zijn/haar verwerver. In een scenario als dit, zal de handelaar aangeven dat het authenticatieproces kan worden overgeslagen door de volgende aanvullende parameters te verzenden:


Parameter Waarden Verplicht / optioneel
FLAG3D N = het 3DS-authenticatieproces overslaan Verplicht (indien 3DS moet worden overgeslagen)
3DS_EXEMPTION_INDICATOR Geef rechtvaardiging voor het overslaan van 3DS. De numerieke waarden kunnen van toepassing zijn afhankelijk van de transactie

03 = TRA* uitgever
04 = Uitzondering laag bedrag
05 = TRA* handelaar/verwerver
06 = Whitelisting
07 = Bedrijf
08 = Vertraagde verzending
09 = Gedelegeerde authenticatie (gecertificeerde wallet)
Verplicht (indien 3DS moet worden overgeslagen)
* Transactierisicoanalyse


Het is echter nog steeds de uitgever die bepaalt of een authenticatieproces moet plaatsvinden. Indien de uitgever eist dat 3DS plaatsvindt, wordt de transactie afgewezen.