Trusted Shops Integratiehandboek

Transcriptie

1 Trusted Shops Integratiehandboek Keurmerk, Garantie Excellence Versie 1.5 nl_nl 2015 Trusted Shops GmbH

2 Inhoud 1. Het Trusted Shops Keurmerk met Garantie Excellence De Trusted Shops Kopersbescherming Trusted Shops Webservice voor het afsluiten van een kopersbescherming Foutafhandeling Integratie van de kopersbescherming op de homepage van de webwinkel De Trusted Shops Trustbadge met de Trustcard Ondersteuning Trusted Shops GmbH 2

3 1. Het Trusted Shops Keurmerk met Garantie Excellence 1.1 De Trusted Shops Kopersbescherming Hoe werkt het? De mogelijkheid om de Trusted Shops Kopersbescherming af te sluiten wordt tijdens het bestelproces in een apart kader aangegeven en kan door de klant in de webwinkel geactiveerd en gedeactiveerd worden door middel van een selectievakje. Wanneer de klant de Trusted Shops Kopersbescherming heeft geselecteerd, wordt deze als extra product aan de bestelling toegevoegd. Het selectievakje is standaard gedeactiveerd. Hetzelfde geldt wanneer de klant de pagina verlaat en deze later opnieuw opent. Dit is bijvoorbeeld het geval wanneer hij in de tussentijd extra producten aan het winkelmandje toevoegt. Afhankelijk van het bedrag in het winkelmandje (waarde producten plus verzendkosten) moet het juiste Trusted Shops Kopersbeschermingsproduct getoond worden. Het juiste product is steeds het goedkoopste Trusted Shops-product dat de aankoop volledig dekt (bijv. bij een aankoop van EUR 600,- dient het product Trusted Shops Kopersbescherming tot EUR 1.500,- geselecteerd te worden). Op de overzichtspagina van de bestelling wordt de eindprijs berekend aan de hand van de kosten voor de kopersbescherming, de kostprijs van de bestelde producten en de verzendkosten. Nadat de bestelling is bevestigd, wordt de webservice van de Trusted Shops Kopersbescherming geopend via de methode requestforprotectionv2() met de betreffende parameters. Het commando getrequeststate() controleert snel of het garantieverzoek door Trusted Shops is goedgekeurd. Vervolgens wordt de garantie in het Trusted Shops Systeem geboekt en wordt de klant per op de hoogte gesteld. Afgesloten garanties kunnen in het ledengedeelte bekeken worden via De webwinkelier dient ervoor te zorgen dat alle aanvragen voor kopersbescherming succesvol verstuurd kunnen worden. Hij dient ook te controleren of alle garanties met succes zijn afgesloten Schematische weergave in de webwinkel De Trusted Shops Kopersbescherming wordt getoond wanneer de klant tijdens het betalen een betalingswijze kiest. Afb. 1: Schematische weergave van de Trusted Shops Kopersbescherming Excellence Technische procedure 2015 Trusted Shops GmbH 3

4 Afb. 2: Technische procedure van de Trusted Shops Kopersbescherming Excellence Eigenschappen en berekening van kopersbeschermingsproducten De Trusted Shops Kopersbescherming wordt afgesloten door tijdens het bestelproces een kopersbeschermingsproduct aan het winkelmandje toe te voegen. De naam van de verschillende kopersbeschermingsproducten bevat steeds het maximale garantiebedrag en de garantieperiode. Product TS080501_500_30_EUR bevat bijvoorbeeld een kopersbescherming tot maximaal EUR 500 met een garantieperiode van 30 dagen. Neem a.u.b. de volgende Trusted Shops Kopersbeschermingsproducten op in uw webwinkel, als u nog geen andere producten heeft ontvangen. Trusted Shops Product ID (tsproductid) Netto prijs TS080501_500_30_EUR TS080501_1500_30_EUR TS080501_2500_30_EUR TS080501_5000_30_EUR TS080501_10000_30_EUR TS080501_20000_30_EUR 0,82353 EUR 2,47059 EUR 4,11765 EUR 8,23530 EUR 16,47060 EUR 32,94120 EUR Voor kopersbeschermingsproducten geldt: De Trusted Shops Kopersbeschermingsproducten worden opgeslagen in de webwinkel resp. de database, maar worden niet in de reguliere productcatalogus van de webwinkel getoond. Kopersbeschermingsproducten kunnen uitsluitend tijdens het betaalproces gekocht worden. Kopersbeschermingsproducten zijn onbeperkt beschikbaar. Ieder winkelmandje mag maximaal één kopersbeschermingsproduct bevatten. Kopersbeschermingsproducten worden altijd als hun netto prijs opgeslagen. Voor kopersbeschermingsproducten gelden dezelfde belastingen en toeslagen als de overige producten. Wanneer voor alle producten hetzelfde BTW-tarief geldt, is deze doorslaggevend Trusted Shops GmbH 4

5 Voor winkelwagentjes met producten waarvoor verschillende BTW-tarieven gelden, adviseren we het hoogste tarief te berekenen. Eventuele vragen of onduidelijkheden kunnen webwinkeliers het beste aan hun belastingadviseur voorleggen. De prijs van de kopersbeschermingsproducten wordt in de webwinkel op dezelfde manier weergegeven als de prijzen van de overige producten. Inclusief BTW voor consumenten en exclusief BTW voor zakelijke klanten. Het factuurbedrag wordt verhoogd met de kosten van de Trusted Shops Kopersbeschermingsproducten. De Trusted Shops Kopersbescherming geldt uitsluitend voor producten uit de webwinkel en daarmee gepaard gaande verzendkosten; de kosten voor de kopersbescherming worden dus niet gedekt. Eventuele kortingen gelden niet voor kopersbeschermingsproducten. In onderstaand voorbeeld voor een winkelmandje bedraagt het factuurbedrag EUR 196,00. De Trusted Shops Kopersbescherming wordt aangevraagd voor een bedrag van EUR 195,00: Voorbeeldfactuur (incl. 21% BTW voor Nederland): Product 1 Product 2 Korting voor betalingswijze 5% Verzendkosten Trusted Shops Kopersbescherming tot EUR 500 Totaalbedrag factuur EUR EUR EUR 5.00 EUR 1.00 EUR EUR Beheer van Trusted Shops-certificaten Een Trusted Shops Certificaat kan worden herkend aan een uit 33 tekens bestaande alfanumerieke code, de zogenaamde Trusted Shops ID (TS-ID). De webwinkelier ontvangt na aanmelding bij Trusted Shops zijn Trusted Shops ID. Een Trusted Shops ID is uitsluitend geldig voor een specifieke shop-url in een specifieke taal. Wanneer een keten meerdere webwinkels of meerdere taalversies van een bepaalde webwinkel beheert, wordt er voor iedere versie of webwinkel een eigen Trusted Shops ID gegeven. Voor ieder Trusted Shops Certificaat wordt bovendien een login verstrekt voor de webservice (WSLogin), waarmee de optie Kopersbescherming kan worden aangevraagd. 1.2 Trusted Shops Webservice voor het afsluiten van een kopersbescherming De webservice voor de front-end van de webwinkel kent twee methoden om kopersbescherming af te sluiten en te controleren. De webservice voor het afsluiten van een kopersbescherming is te bereiken via de volgende URI's bij Trusted Shops. Webservice URI voor de testomgeving ( Sandbox ) Webservice URI voor de productieomgeving tservice?wsdl requestforprotectionv2() De methode requestforprotectionv2() is de centrale functie binnen het proces om de kopersbeschermingsgarantie af te sluiten. De vereiste gegevens van de transactie worden aan Trusted Shops doorgestuurd en de webservice produceert een aanvraag voor de 2015 Trusted Shops GmbH 5

6 kopersbescherming. De aanvragen worden door Trusted Shops formeel gecontroleerd op geldigheid, opgeslagen en op regelmatige basis verwerkt. Wij verwijzen u tevens naar de instructies m.b.t. de foutafhandeling, zodat u er steeds zeker van kunt zijn dat aanvragen voor kopersbescherming met succes via de interface verstuurd kunnen worden Omschrijving en gegevenstypes WSDL-definitie: <message name="applicationrequestservice_requestforprotectionv2"> <part name="tsid" type="xsd:string"/> <part name="tsproductid" type="xsd:string"/> <part name="amount" type="xsd:decimal"/> <part name="currency" type="xsd:string"/> <part name="paymenttype" type="xsd:string"/> <part name="buyer " type="xsd:string"/> <part name="shopcustomerid" type="xsd:string"/> <part name="shoporderid" type="xsd:string"/> <part name="orderdate" type="xsd:datetime"/> <part name="shopsystemversion" type="xsd:string"/> <part name="wsuser" type="xsd:string"/> <part name="wspassword" type="xsd:string"/> </message> Parameter Parameter Beschrijving Commentaar tsid tsproductid amount currency paymenttype Trusted Shops ID van het certificaat Kopersbescherming Productcode Factuurbedrag incl. Verzendkosten Valuta van de aankoop, ISO tekens Betalingswijze constante buyer adres van de koper Verplicht shopcustomerid Klantnummer van de koper shoporderid Bestelnummer van de koper Verplicht orderdate shopsystemversion Datum van de bestelling bij de webwinkel Versie van de webwinkel software en eventueel van de Trusted Shops-module, bijv. topshop v2.1 Verplicht, wordt door Trusted Shops per certificaat verstrekt; iedere taalversie en iedere afzonderlijke webwinkel in een zogenaamd multishopsysteem vereist een eigen certificaat Verplicht, zie tabel met Kopersbeschermingsproducten Verplicht, formaat met een punt als decimaal scheidingsteken, twee cijfers achter de komma (bijv ) Verplicht, bijv. ISO-code voor euro = EUR Verplicht, specifiek voor Trusted Shops, zie opsomming van beschikbare betalingswijzen Verplicht, indien niet ingevuld waarde 0 versturen Verplicht, Formaat: T09:30:00 Verplicht, string 2015 Trusted Shops GmbH 6

7 wsuser wspassword Webservice Gebruiker Webservice Wachtwoord Verplicht, wordt door Trusted Shops per certificaat verstrekt Verplicht, wordt door Trusted Shops per certificaat verstrekt Antwoord Een positief antwoord betekent dat de webservice de aanvraag met succes verwerkt heeft. De waarde komt overeen met het aanvraagnummer van de kopersbescherming. Een negatieve restitutiewaarde duidt op een fout; de waarde geeft de foutcode aan Voorbeeldcode (PHP) Hieronder wordt een voorbeeld gegeven van een aanvraag via de interface nadat de klant een bestelling heeft geplaatst en afgesloten. Een voorwaarde is de PHP 5 SOAP-extensie. Gemarkeerde passages dienen aangepast te worden. Voorbeeld PHP-code (geel gemarkeerde tekst vervangen a.u.b.): define("soap_error", -1); define("ts_server", "protection.trustedshops.com"); # Collect parameters for the webservice call # TS-ID received by Trusted Shops $tsid = "X ABCDEFGHJKLMNOPQRSTUVW"; # Defined by Trusted Shops, depends on order total amount $tsproductid = "TS080501_500_30_EUR"; $orderdate = date("y-m-d", time()). "T". date("h:i:s", time()); $shopsystemversion = "Shop 4.0 TS.01"; # Collect other parameters $decimalamount = (double) $amount; #... # Call TS protection webservice $ini = ini_set("soap.wsdl_cache_enabled", 1); try { $wsdlurl = " TS_SERVER. "/ts/protectionservices/applicationrequestservice?wsdl"; $client = new SoapClient($wsdlUrl); # Set return value for the case if a SOAP exception occurs $returnvalue = SOAP_ERROR; # call WS method $returnvalue = $client-> requestforprotectionv2 ($tsid, $tsproductid, (double)$amount, $currency, $paymenttype, $buyer , $shopcustomerid, $shoporderid, $orderdate, $shopsystemversion, $wsuser, $wspassword); } catch (SoapFault $fault) { $errortext = "SOAP Fault: (faultcode: {$fault->faultcode}, faultstring: {$fault- >faultstring})"; echo $errortext; } # Check return value # Negative return value is an error code, positive value is the application number if ($returnvalue == SOAP_ERROR) { echo "SOAP error: $errortext"; } else if ($returnvalue < 0) { echo "TS Webservice returns error code $returnvalue"; switch ($returnvalue) { case : echo "Cause: login failed or no valid shop found for tsid '$tsid'"; 2015 Trusted Shops GmbH 7

8 break;... } } else { echo "TS Webservice has successfully returned application number '$returnvalue'"; } Betalingswijzen Bij het afsluiten van de Trusted Shops Kopersbescherming wordt de door de klant geselecteerde betalingswijze aan Trusted Shops doorgestuurd. De door Trusted Shops ondersteunde betalingsmogelijkheden worden als volgt aangegeven. Koppel a.u.b. de in uw webwinkel geaccepteerde betalingsmogelijkheden aan de betalingsmogelijkheden van Trusted Shops. Code DIRECT_DEBIT CREDIT_CARD INVOICE CASH_ON_DELIVERY PREPAYMENT CHEQUE PAYBOX PAYPAL AMAZON_PAYMENTS CASH_ON_PICKUP FINANCING LEASING T_PAY CLICKANDBUY GIROPAY GOOGLE_CHECKOUT SHOP_CARD DIRECT_E_BANKING MONEYBOOKERS DOTPAY PLATNOSCI PRZELEWY24 OTHER NL Machtiging / automatische incasso Creditcard Factuur Onder rembours Vooruitbetaling / overboeking Cheque Paybox PayPal Amazon Payments Betaling bij afhalen Op afbetaling Leasing T-Pay Click&Buy Giropay Google Checkout Betaalkaart van de webwinkel SOFORT Banking moneybookers.com Dotpay Płatności Przelewy24 Andere betalingswijze 2015 Trusted Shops GmbH 8

9 1.2.2 getrequeststate() Via de methode getrequeststate() wordt de status van een garantieaanvraag opgevraagd en in het geval van een succesvolle boeking wordt het garantienummer verstrekt. Een positief antwoord van requestforprotectionv2()betekent, dat de aanvraag voor kopersbescherming succesvol verstuurd is en zich in de wachtrij bij Trusted Shops bevindt. Semantische fouten (bijv. ontbrekende of dubbele bestelnummers) worden pas tijdens de verwerking van de aanvraag als zodanig herkend. Door middel van de opdracht getrequeststate() wordt daarom gecontroleerd, of de met behulp van de opdracht requestforprotectionv2() opgevraagde garantieaanvragen door Trusted Shops in behandeling zijn genomen. Alleen bij succesvol verwerkte aanvragen wordt de garantieaanvraag goedgekeurd. Trusted Shops raadt daarom aan, de opdracht door middel van een cronjob met een interval van 10 minuten te automatiseren. Omdat er een bepaalde verwerkingstijd zit tussen de aanvraag van de kopersbescherming in de webwinkel en de uiteindelijke bevestiging door Trusted Shops, dient een foutafhandelingsprocedure geïnstalleerd te worden. Na downtime van Trusted Shops of na SOAP-exceptions kunnen garantieaanvragen tot drie dagen later (met aangepaste transactiedata) opnieuw in behandeling genomen worden Omschrijving en gegevenstypes WSDL-definitie: <message name="applicationrequestservice_getrequeststate"> <part name="tsid" type="xsd:string"/> <part name="applicationid" type="xsd:long"/> </message> Parameter Parameter Beschrijving Commentaar tsid applicationid Trusted Shops ID van het certificaat Aanvraagnummer kopersbescherming Verplicht, wordt door Trusted Shops per certificaat verstrekt; iedere taalversie en iedere afzonderlijke webwinkel in een zogenaamd multishopsysteem vereist een eigen certificaat Verplicht, antwoord van requestforprotectionv2() Antwoord Een positief antwoord betekent, dat de webservice de aanvraag met succes verwerkt heeft. De waarde komt overeen met het garantienummer. Een negatieve restitutiewaarde duidt op een fout; de waarde geeft de foutcode aan. 1.3 Foutafhandeling Houd alle foutmeldingen en SOAP-exceptions bij tijdens de integratie en de productie, zodat fouten tijdens de implementatie of configuratie al in een vroeg stadium herkend kunnen worden. Met het oog op eventuele onvoorziene foutmeldingen of een onbereikbare website van Trusted Shops, garandeert een juiste foutafhandeling dat iedere aanvraag voor kopersbescherming Trusted Shops uiteindelijk bereikt. De webwinkelier is er verantwoordelijk voor dat elke aanvraag voor kopersbescherming aan Trusted Shops wordt doorgestuurd. Aanvragen voor kopersbescherming kunnen met aangepaste data binnen drie dagen opnieuw worden aangeboden. De actuele status van een garantie kan met behulp van de opdracht getrequeststate() gecontroleerd worden. Functie Beschrijving Commentaar 2015 Trusted Shops GmbH 9

10 Afhandeling van de wachtrij Logboek Opslag en verwerking van garantieaanvragen Registreren van garantieaanvragen, foutmeldingen, SOAP-exceptions enz. Verplicht, bijvoorbeeld via retry maximaal 3 maal met een interval van 8 uur, daarna annuleren Verplicht, bijvoorbeeld in de vorm van een log van afgesloten garanties op het dashboard van de shopbeheersomgeving Foutmeldingen Code Antwoord Oorzaak NO_VALID_SHOP Ongeldige TS-ID of login voor de webservice LIMIT_CANCELLED De kredietlimiet van de webwinkel is door Trusted Shops opgeheven DUPLICATE_ORDER_NUMBER Bestelnummer meerdere keren gebruikt UNSUPPORTED_TS_PRODUCT Kopersbeschermingsproduct niet ondersteund INACTIVE_PAYMENT_TYPE Betalingswijze niet geactiveerd UNSUPPORTED_PAYMENT_TYPE Betalingswijze niet ondersteund CURRENCY_MISMATCH UNSUPPORTED_CURRENCY De valuta van het kopersbeschermingsproduct komt niet overeen met de valuta van het winkelmandje De gekozen valuta wordt door deze shop niet geaccepteerd UNSUPPORTED_EXCHANGE_RATE De wisselkoers wordt niet ondersteund NOT_PERSISTENT_PAYMENT_TYPE De betalingswijze wordt niet ondersteund NO_LIMIT Geen kredietlimiet aanwezig voor dit certificaat PAST_DELIVERY_DATE TOO_OLD_ORDER De afleveringsdatum bevindt zich in het verleden De garantie werd aangevraagd voor een aankoop die meer dan 3 dagen geleden werd gedaan _MALFORMED Het formaat van het adres is onjuist ORDER_ID_EMPTY Er werd geen bestelnummer meegezonden CUSTOMER_ID_EMPTY Er werd geen klantnummer meegezonden LIMIT_OVERFLOW De kredietlimiet voor dit certificaat is overschreden _EMPTY Er werd geen adres meegezonden WRONG_TS_PRODUCT Er is een onjuist kopersbeschermingsproduct aangegeven L ORDER_DATE_FUTURE De besteldatum ligt in de toekomst INVALID_SECURITY_TOKEN Token ongeldig 2015 Trusted Shops GmbH 10

11 SYSTEM_EXCEPTION Algemene systeemfout, neem a.u.b. contact op met Trusted Shops Typische SOAP-exceptions Tijdens de implementatiefase en in productie kunnen SOAP-exceptions optreden. Deze typische uitzonderingsgevallen hebben de volgende oorzaken: Foutmeldingen Invalid number of payload elements: 12 Error code: env:server java.lang.numberformatexception Date value does not follow the format... String index out of range: 0 Oorzaak Aantal en volgorde van de verstuurde parameters controleren ongeldig bedrag ongeldige datum lege datum Codes voor testomgevingen Tijdens de implementatiefase gebruikt u de volgende codes voor de afzonderlijke talen. De codes voor de productieomgeving ontvangt u van uw contactpersoon bij Trusted Shops wanneer uw webwinkel wordt vrijgegeven. Webservice-codes voor NL: Trusted Shops ID (tsid): Gebruikersnaam (wsuser): X41495A6E65ECDDCD554A02C0601D1C97 testexcellencepartner Wachtwoord (wspassword): test Integratie van de kopersbescherming op de homepage van de webwinkel Locatie van het Trusted Shops selectievak kopersbescherming Het kader met de Trusted Shops Kopersbescherming Excellence dient duidelijk zichtbaar te zijn tijdens de selectie van de gewenste betalingswijze Teksten binnen het Trusted Shops selectievak kopersbescherming Afb. 3: Voorbeeld van de Kopersbescherming Excellence in EUR In het kader voor de kopersbescherming dienen onderstaande teksten gebruikt te worden voor de betreffende taal van de webwinkel. De berekende omzetbelasting wordt in principe aangegeven zonder vermelding van het percentage, maar met de toevoeging incl. BTW (resp. excl. BTW voor bestellingen van zakelijke klanten). Landspecifieke tekst voor taal NL (geel gemarkeerde tekst vervangen a.u.b.): [ ] Trusted Shops koperbescherming (aanbevolen) 2015 Trusted Shops GmbH 11

12 Koperbescherming tot 500 EUR (1,00 EUR incl. BTW) De in de koperbescherming inbegrepen Trusted Shops Garantie beveiligt uw online aankoop. Ik ga akkoord met de doorgifte en de opslag van mijn adres voor de afwikkeling van de koperbescherming door Trusted Shops. Garantievoorwaarden voor de koperbescherming Links van en naar het selectievak kopersbescherming Het Trusted Shops-logo en de gemarkeerde begrippen dienen taalonafhankelijk als volgt te worden gelinkt. De parameter shop_id komt overeen met het Trusted Shops ID van het certificaat. Gebruik voor links steeds de parameter target= _blank, waardoor de pagina steeds in een nieuw browservenster of -tab wordt geopend. URL-link naar Trusted Shops-logo (geel gemarkeerde tekst vervangen a.u.b.): URL-link "Opslag" (geel gemarkeerde tekst vervangen a.u.b.):" URL Link "Trusted Shops Garantie", "Garantievoorwaarden" (geel gemarkeerde tekst vervangen a.u.b.): De Trusted Shops Trustbadge met de Trustcard Trusted Shops heeft een nieuwe integratietechnologie ontwikkeld waarmee de Trusted Shops leden hun betrouwbaarheid vanaf het eerste moment sterk onder de aandacht van hun klanten kunnen brengen de Trustbadge. Via leest u hoe u de Trustbadge-code kunt genereren en in uw webwinkel kunt integreren. Hier staat ook een preview-functie tot uw beschikking waarmee u de verschillende varianten van de Trustbadge meteen kunt uitproberen binnen de lay-out van uw webwinkel. URL voor de Trustbadge-integratie: 2. Ondersteuning Neemt u bij vragen over de integratie van het Trusted Shops Keurmerk met Kopersbescherming of de Klantbeoordeling a.u.b. contact op met: Trusted Shops GmbH Ledenservice Tel: members@trustedshops.nl 2015 Trusted Shops GmbH 12