Alias Manager
Inhoudsopgave 1. Inleiding 2. Een Alias aanmaken 2.1 e-commerce 2.1.1 Extra verborgen velden 2.1.2 Beveiliging: SHA-handtekening (controle voor de betaling) 2.1.3 Transactiefeedback aan de merchant 2.2 DirectLink 2.2.1 Aanvullende verzoekparameters 2.2.2 Beveiliging: SHA-handtekening (controle voor de betaling) 2.2.3 Transactieantwoord 2.3 Batch 2.4 Alias Manager 3. Gebruik van de Alias 3.1 e-commerce 3.1.1 Alias-update 3.2 DirectLink 3.2.1 Alias-update 3.3 Batch 3.3.1 Alias-update 3.4 e-terminal 3.4.1 Alias-update 3.5 Fouten 4. Aliasbeheer Page 1 of 12-12/09/2017
5. Speciale toepassingen 5.1 e-wallet 6. Appendix: Bulk Alias-aanmaak via Batch 6.1 Overzicht 6.2 Aanmaak 6.3 Verwijderen Page 2 of 12-12/09/2017
1. Inleiding De Alias Manager biedt functies voor periodieke facturering (betaling van periodiek gefactureerde diensten) en andere specifieke toepassingen met kaartnummeraliassen (opslag van klantenprofielen op uw website bijvoorbeeld). Een alias is een identificatie voor een kaartnummer en de vervaldatum van de kaart en kan gebruikt worden om andere betalingen in de toekomst aan te vragen. Deze alias wordt aan een enkele merchant gekoppeld en kan niet door een derde gebruikt worden. Dankzij de Alias Manager voor periodieke facturering (recurring) hoeven merchants die Batch, DirectLink en/of e-terminal gebruiken de financiële gegevens van hun klanten na de eerste betaling niet op te slaan. Merchants die e-commerce gebruiken, hoeven nooit in contact te komen met de financiële gegevens van hun klanten of hen op te slaan. Dit beperkt de risico s en investeringen met betrekking tot de veilige opslag van de financiële gegevens van klanten. De Alias Manager laat het gebruik van een veilig periodiek factureringssysteem toe zonder dat de merchant zijn systeem PCI-compatibel hoeft te maken. Zelfs wanneer de Alias Manager in uw account actief is, kunt u nog altijd transacties uitvoeren zonder een alias te specificeren. Wanneer u in de e-commerce-modus werkt, vragen we de klant of zijn financieel profiel opgeslagen mag worden. Aangezien ons systeem in overeenstemming is met de wetgeving betreffende de persoonlijke levenssfeer, kan een kaarthouder ons weigeren om zijn financieel profiel op te slaan. In dat geval kan de merchant beslissen om de transactie af te breken als de aanmaak van een alias cruciaal is. Deze beperking is niet van toepassing op de andere modi, waarbij de merchant zelf de financiële gegevens van de kaarthouder invoert. Dit document beschrijft de integratie van de optie Alias Manager" in de toepassing van de merchant (e-commerce / DirectLink / Batch / e-terminal). Deze optiehandleiding moet samen met de integratiehandleidingen van e-commerce / DirectLink / Batch / e-terminal gelezen worden. Page 3 of 12-12/09/2017
2. Een Alias aanmaken U kunt een alias aanmaken door een transactie uit te voeren via e-commerce, DirectLink of Batch. Daarnaast kunt u ook handmatig (via e-terminal) een alias aanmaken op de Alias management-pagina. U kunt ook geen tekenreeks van cijfers met meer dan 14 tekens beginnend met 2, 3, 4, 5 of 6 gebruiken die op een kaartnummer lijkt. Dit wordt geblokkeerd door ons syteem, omwille van het onveilige aspect om niet-geëncrypteerde kaartnummers in ons systeem op te slaan. De mogelijkheid om met een alias te werken voor periodieke facturering en andere specifieke toepassingen, hangt af van de betaalmethodes die u wenst te gebruiken. Zie de online betalingsmethoden Processing / Procedure overzichtspagina. 2.1 e-commerce De procedure voor het aanmaken van een alias in de e-commerce-modus is bijna identiek aan die van een normale e-commerce-transactie. Het grootste technische verschil ligt in de wijzigingen die uitgevoerd moeten worden bij de controle voor de betaling. 2.1.1 Extra verborgen velden Om een alias via e-commerce aan te maken, moet u de volgende extra verborgen velden doorsturen: Veld Verklaring ALIAS Alias voorgesteld door de merchant ALIASUSAGE Een tekst die de reden voor de aliasregistratie opgeeft Na het verzenden van de verborgen velden wordt de veilige betaalpagina aan de klant getoond. Daar kan hij zijn betaalmethode kiezen en zijn betalingsgegevens invoeren. Ook de tekst die u in het ALIASUSAGE-veld hebt doorgestuurd, wordt weergegeven. Het dialoogvenster bevat een selectievakje dat de klant kan aan- of uitvinken om zijn toestemming te geven of te weigeren voor de opslag van zijn financieel profiel. Indien niet aangevinkt, dan kunt u als merchant het transactieproces automatisch stopzetten. Dit kunt u op de Alias Management-pagina instellen (via "Configuratie" > "Alias" in het backofficemenu). Als de transactie op ons platform met succes verwerkt wordt (niet in status 0 of 1), dan maken wij het financieel profiel (alias) in onze aliasdatabase aan. 2.1.2 Beveiliging: SHA-handtekening (controle voor de betaling) U moet de alias-parameters (ALIAS and ALIASUSAGE) gebruiken in de berekening van de SHA signature. Voor meer details, ga naar e-commerce. 2.1.3 Transactiefeedback aan de merchant Page 4 of 12-12/09/2017
Als u na de transactie feedback-requests ontvangt, of feedbackparameters op een redirectie, dan zult u een extra parameter ontvangen: ALIAS. Als u een SHA-OUT-handtekening voor deze feedback-requests hebt ingesteld, dan moet u de ALIAS-parameter in acht nemen voor uw handtekening. 2.2 DirectLink 2.2.1 Aanvullende verzoekparameters Om tijdens een transactie via DirectLink een alias aan te maken, moet u naast de andere transactievelden ook de volgende velden doorsturen: Veld Beschrijving ALIAS Alias voorgesteld door de merchant CARDNO Kaartnummer ED Vervaldatum CN Naam kaarthouder Als de transactie op ons platform met succes verwerkt wordt (niet in status 0 of 1), dan maken wij het financieel profiel (alias) in onze aliasdatabase aan. Voor Direct Debits moet het rekeningnummer in het veld CARDNO worden meegezonden, de vervaldatum mag niet worden verzonden. 2.2.2 Beveiliging: SHA-handtekening (controle voor de betaling) U moet de alias parameters (ALIAS and ALIASUSAGE) gebruiken in de berekening van de SHA-handtekening. Voor meer details, ga naar e-commerce. 2.2.3 Transactieantwoord Het XML antwoord op uw verzoek zal de extra parameter ALIAS bevatten. 2.3 Batch Om tijdens een transactie via Batch een alias aan te maken, moet u naast de andere transactievelden ook de volgende velden doorsturen: Veld Veldnummer ALIAS 17 CN 4 ED 5 CN 8 Als de transactie op ons platform met succes verwerkt wordt (niet in status 0 of 1), dan maken wij het financieel profiel (alias) in onze aliasdatabase aan. Page 5 of 12-12/09/2017
2.4 Alias Manager Aliassen kunnen handmatig in het backoffice geregistreerd worden: 1. 2. 3. 4. Ga naar "Configuratie" > "Alias" in het menu van uw account om de Alias Management-pagina te openen. Klik op de tab "Aanmaken" om een nieuwe alias te registreren. Voer de aliasnaam en de financiële gegevens in: naam kaart/rekeninghouder, kaartnummer en vervaldatum (indien van toepassing) Klik op de knop Aanmaken. $ENDIF Aangezien de alias handmatig aangemaakt wordt in plaats van via een transactie, maken wij het financieel profiel (alias) niet onmiddellijk in onze aliasdatabase aan. Wij kunnen het financieel profiel pas in onze database invoeren wanneer een transactie met de alias door de financiële instelling aanvaard is, m.a.w. nadat de betalingsgegevens officieel gecontroleerd zijn. Page 6 of 12-12/09/2017
3. Gebruik van de Alias De mogelijkheid om met een Alias te werken voor periodieke facturering en andere specifieke toepassingen hangt af van de betaalmethodes die u wenst te gebruiken. 3.1 e-commerce Om een bestaande ALIAS te gebruiken, kunnen of moeten de volgende verborgen velden meegestuurd worden in uw request: Veld Omschrijving Verplicht ALIAS De naam van de ALIAS die u wilt gebruiken. Wij controleren dan of de ALIAS voor uw PSPID al bestaat. J ALIASUSAGE Stuur een waarde met dit veld enkel als u een andere tekst aan de klant wilt tonen dan degene die u initieel had gestuurd bij het aanmaken van de alias. N ECI ECI-waarde "9" moet gestuurd worden bij wederkerende transacties J Als de ALIAS bestaat, dan worden de naam van de kaarthouder, het gemaskeerde creditcardnummer en de vervaldatum op de betaalpagina geïnitialiseerd. 3.1.1 Alias-update Als de kaarthouder de vooraf ingestelde gegevens niet wijzigt en gewoon op de knop Verzenden klikt, dan zoeken we het financieel profiel (gebaseerd op de ALIAS) in de database op. Indien hij bepaalde gegevens, zoals de vervaldatum, wil bijwerken, kan de kaarthouder de geïnitialiseerde velden wijzigen. Als de transactie op ons platform met succes verwerkt wordt (niet in status 0 of 1), dan zullen we de financiële gegevens van de klant bijwerken. Voor meer informatie over de controle voor de betaling en feedback-requests na de transactie, raadpleeg Alias aanmaken via e-commerce. 3.2 DirectLink Om een bestaande ALIAS te gebruiken, moeten de volgende velden meegestuurd worden in uw request: Veld Omschrijving ALIAS De naam van de ALIAS die u wilt gebruiken. Wij controleren dan of de ALIAS voor uw PSPID al bestaat. ECI ECI-waarde "9" moet gestuurd worden bij wederkerende transacties Als de ALIAS bestaat, dan worden de naam van de kaarthouder, het gemaskeerde creditcardnummer en de vervaldatum op de betaalpagina geïnitialiseerd. 3.2.1 Alias-update Als u ons gewoon de ALIAS doorstuurt (geen nieuw creditcardnummer, vervaldatum, naam kaarthouder), dan zoeken wij het financieel profiel (gebaseerd op de ALIAS) in de database op. Naast de ALIAS-parameter kunt u ons ook een nieuw creditcardnummer, vervaldatum of naam van de kaarthouder doorsturen om de bestaande ALIAS bij te werken. Als de transactie op ons platform met succes verwerkt wordt (niet in status 0 of 1), dan zullen we de Page 7 of 12-12/09/2017
financiële gegevens van de klant bijwerken. 3.3 Batch Om een bestaande ALIAS te gebruiken, moet u de volgende velden meesturen in het bestand: Veld Omschrijving Veldnr. ALIAS De naam van de ALIAS die u wilt gebruiken. Wij controleren dan of de ALIAS voor uw PSPID al bestaat. 17 ECI ECI-waarde "9" moet gestuurd worden bij wederkerende transacties. 35 3.3.1 Alias-update Als u ons de ALIAS doorstuurt, dan zoeken wij het financieel profiel (gebaseerd op de ALIAS) in de database op. Naast het ALIAS-veld kunt u ons ook een nieuw creditcardnummer, vervaldatum of naam van de kaarthouder doorsturen om de bestaande ALIAS bij te werken. Als de transactie op ons platform met succes verwerkt wordt (niet in status 0 of 1), dan zullen we de financiële gegevens van de klant bijwerken. 3.4 e-terminal Om een alias te gebruiken via e-terminal volgt u deze stappen: 1. 2. 3. Klik in het backofficemenu op de Alias link Zoek de alias die u wilt gebruiken op in de Alias Management-pagina Klik op de knop Gebruiken. De e-terminal voucher wordt weergegeven met de geïnitialiseerde naam van de kaarthouder, het kaartnummer en de vervaldatum. 3.4.1 Alias-update U kunt enkel de vervaldatum wijzigen op de voucher. De geïnitialiseerde naam van de kaarthouder en het kaartnummer kunnen niet op de voucher gewijzigd worden. 3.5 Fouten Als bij een transactie een alias wordt verzonden, maar ons systeem de alias niet kan vinden (meestal wanneer de alias niet bestaat), worden de volgende foutcode en foutmelding geretourneerd: Retourveld Waarde NCERROR 50001111 (Gegevensvalidatiefout) NCERRORPLUS Alias "..." not Found (niet gevonden) Page 8 of 12-12/09/2017
4. Aliasbeheer Klik op "Configuratie" > "Alias" in uw back-officemenu om toegang te krijgen tot uw Aliasbeheerpagina. Deze pagina bevat de volgende onderdelen: Mijn aliasgegevens: Status: Aantal actieve aliassen (aanklikbaar om een lijst te bekomen van de betreffende aliassen) Aantal aliassen met bijna verlopen creditcardgegevens (aanklikbaar om een lijst te bekomen van de betreffende aliassen) Aantal aliassen die werden verwijderd in de huidige kalendermaand Aantal actieve aliassen in de vorige kalendermaand Algemene parameters: Hier configureert u: of het opt-in/out selectievakje op de betaalpagina al dan niet is aangevinkt. De kaarthouder kan alsnog kiezen zijn kaartgegevens al dan niet te bewaren door het vakje aan/uit te vinken. of een transactie moet geweigerd worden als de kaarthouder kiest om zijn gegevens niet te laten bewaren, en dus geen alias te laten aanmaken de bewaartermijn: hoeveel maanden een alias moet bewaard worden (tussen 3 en 60 maanden/5 jaar). Deze periode wordt na elk gebruik geherinitialiseerd. Aliaslijst, voor het raadplegen en downloaden, opzoeken, gebruiken, wijzigen en verwijderen van aliassen. Aanmaken, voor het manueel aanmaken van nieuwe aliassen. Page 9 of 12-12/09/2017
5. Speciale toepassingen Dit hoofdstuk geeft meer uitleg over specifieke, geavanceerde aliastoepassingen die een hoger niveau van integratie vereisen. Deze toepassingen zijn niet van toepassing voor periodieke (recurring) betalingen. De mogelijkheid om met een Alias te werken voor periodieke facturering en andere specifieke toepassingen hangt af van de betaalmethodes die u wenst te gebruiken. 5.1 e-wallet U kunt geregistreerde klanten een e-wallet van creditcards geven zonder dat u hun financiële gegevens hoeft te beheren. U maakt een nieuwe alias aan voor de eerste betaling van een nieuwe klant. Wanneer de klant uw website opnieuw bezoekt, kunt u de gemaskeerde kaart(en) die aan zijn alias(sen) gekoppeld zijn op de achtergrond (in uw HTML-code) weergeven. De eenvoudigste manier om de gemaskeerde kaartnummers te registreren, is hen te onttrekken uit de feedbackparameters die we u na elke transactie doorsturen (e-commerce). Voorbeeld van een e-wallet: <select name= cards > <option value= alias284 >VISA XXXXXXXXXXXX1111</option> <option value= alias128 >MasterCard XXXXXXXXXXXX9999</option> <option value= alias389 >Use a new card</option> </select> Wanneer de klant (een van) zijn gemaskeerde kaart(en) op uw website selecteert, wordt de gekoppelde alias naar ons doorgestuurd in uw verborgen velden. U kunt nog altijd de keuze Andere kaart aanbieden om het aanmaakproces van een nieuwe alias op te starten. Page 10 of 12-12/09/2017
6. Appendix: Bulk Alias-aanmaak via Batch 6.1 Overzicht Het doel van Bulk Alias-aanmaak via Batch is om meerdere aliassen in een keer aan te maken, zonder transacties uit te voeren. De merchant dient de batchbestanden in "BYMERCHANT"-modus te verstrekken, inclusief de Alias ID. De batchbestanden kunnen zowel manueel als automatisch worden geüpload, via een http-request op het KBC/CBC-Paypage platform. Dit kan synchroon of asynchroon gedaan worden, hoewel we aanraden om de bestanden asynchroon te behandelen indien deze meer dan 100 records bevatten. Op deze manier worden er geen transacties uitgevoerd. Een format check zorgt ervoor dat de creditcard- of rekeningnummers correct zijn, zonder dat een autorisatie wordt uitgevoerd. Dit heeft als gevolg dat er geen zekerheid is of de kaart/rekening nog geldig is. Als de vervaldatum van een creditcard in het verleden ligt, voegt ons systeem twee jaar toe, tot de datum in de toekomst ligt. Dit is een standaard proces bij het aanmaken van een alias. De merchant kan zijn bestanden voor aliasaanmaak op twee verschillende manieren uploaden: 1. Handmatig: de merchant upload de bestanden manueel in zijn back-office (zie Basic Batch). 2. Automatisch: de merchant voert de upload requests met een eigen applicatie uit via https, op specifieke pagina's op ons systeem (zie Advanced Batch). Voor meer informatie, ga naar Advanced Batch voor request URL en specifieke parameters. 6.2 Aanmaak Het bestand met het verzoek moet een ASCII tekstbestand zijn en mag slechts een lijn per alias bevatten. De velden dienen te worden gescheiden met een puntkomma (";") en de waarden zelf mogen geen puntkomma bevatten. Formaat: AN= Alfanumeriek / N=Numeriek, maximum aantal aanvaarde tekens Veld Formaat Voorbeeld 1 OPERATION AN, 8 ADDALIAS 2 ALIAS AN, 50 Customer123 3 CN AN, 35 John Doe 4 CARDNO AN, 21 XXXXXXXXXXXX1111 5 EXPDATE MMYY 1012 6 BRAND AN, 25 VISA 7 PSPID AN, 30 JDoeSHOP Voorbeeld met creditcard: ADDALIAS;Customer123;John Doe;XXXXXXXXXXXX1111;1015;VISA;JDoeSHOP; Voorbeeld met Direct Debits: ADDALIAS;Customer123;John Doe;XXXXXXXXXXXX1111;1015;VISA;JDoeSHOP; 6.3 Verwijderen Het bestand met het verzoek moet een ASCII tekstbestand zijn en mag slechts een lijn per alias bevatten. De velden dienen te worden Page 11 of 12-12/09/2017
gescheiden met een puntkomma (";") en de waarden zelf mogen geen puntkomma bevatten. Formaat: AN= Alfanumeriek / N=Numeriek, maximum aantal aanvaarde tekens Veld Formaat Voorbeeld 1 OPERATION A, 8 DELALIAS 2 ALIAS AN, 50 Customer123 Voorbeeld: DELALIAS;Customer123;;;;;; (alle puntkomma's aan het eind moeten toegevoegd worden!) Automatische file upload: Om de verwijdering van een alias tot stand te brengen is een bestand met het volgende formaat nodig: OHL;PSPID;API PASSWORD;;USER API; DELALIAS;ALIAS VALUE;;;;;; DELALIAS;ALIAS VALUE;;;;;; OTF; Wij raden aan om checkandprocess (controleren en verwerken) te gebruiken en alleen aliassen van dezelfde PSPID te vermelden. Voor meer informatie over de verschillende automatische upload processen, ga naar Advanced Batch. Page 12 of 12-12/09/2017