Trusted Shops Integratiehandboek

Trusted Shops Integratiehandboek Keurmerk, Garantie Excellence

Versie 1.5 nl_NL © 2015 Trusted Shops GmbH

Integratiehandboek voor webwinkeliers

Inhoud 1. 1.1 1.2 1.3 1.4 1.5

2.

Het Trusted Shops Keurmerk met Garantie Excellence ......................................... 3 De Trusted Shops Kopersbescherming ................................................................................... 3 Trusted Shops Webservice voor het afsluiten van een kopersbescherming ........................... 5 Foutafhandeling ....................................................................................................................... 9 Integratie van de kopersbescherming op de homepage van de webwinkel .......................... 11 De Trusted Shops Trustbadge met de Trustcard .................................................................. 12

Ondersteuning ........................................................................................................ 12

© 2015 Trusted Shops GmbH

2


1. Het Trusted Shops Keurmerk met Garantie Excellence 1.1

De Trusted Shops Kopersbescherming

1.1.1 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 e-mail op de hoogte gesteld. Afgesloten garanties kunnen in het ledengedeelte bekeken worden via https://www.trustedshops.com/de/shop/login.html. 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. 1.1.2 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

1.1.3

Technische procedure


3


Afb. 2: Technische procedure van de Trusted Shops Kopersbescherming Excellence

1.1.4 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

0,82353 EUR

TS080501_1500_30_EUR

2,47059 EUR

TS080501_2500_30_EUR

4,11765 EUR

TS080501_5000_30_EUR

8,23530 EUR

TS080501_10000_30_EUR

16,47060 EUR

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


4


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

150.00 EUR 50.00 EUR - 10.00 EUR 5.00 EUR 1.00 EUR -----------196.00 EUR

1.1.5 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”) https://protectionqa.trustedshops.com/ts/protectionservices/ApplicationRequestService?wsdl

Webservice URI voor de productieomgeving https://protection.trustedshops.com/ts/protectionservices/ApplicationReques tService?wsdl 1.2.1 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


5


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

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="buyerEmail" 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"/> 1.2.1.2

Parameter

Parameter

Beschrijving

Commentaar

tsID

Trusted Shops ID van het certificaat

Verplicht, wordt door Trusted Shops per certificaat verstrekt; iedere taalversie en iedere afzonderlijke webwinkel in een zogenaamd “multishopsysteem” vereist een eigen certificaat

tsProductID

Kopersbescherming Productcode

Verplicht, zie tabel met Kopersbeschermingsproducten

amount

Factuurbedrag incl. Verzendkosten

Verplicht, formaat met een punt als decimaal scheidingsteken, twee cijfers achter de komma (bijv. 3130.47)

currency

Valuta van de aankoop, ISO 4217 3 tekens

Verplicht, bijv. ISO-code voor euro = EUR

paymentType

Betalingswijze constante

Verplicht, specifiek voor Trusted Shops, zie opsomming van beschikbare betalingswijzen

buyerEmail

E-mailadres van de koper

Verplicht

shopCustomerID

Klantnummer van de koper

Verplicht, indien niet ingevuld waarde “0” versturen

shopOrderID

Bestelnummer van de koper

Verplicht

orderDate

Datum van de bestelling bij de webwinkel

Verplicht, Formaat: 2011-10-31T09:30:00

shopSystemVersion

Versie van de webwinkel software en eventueel van de Trusted Shops-module, bijv. “topshop v2.1”

Verplicht, string


6


wsUser

Webservice Gebruiker

Verplicht, wordt door Trusted Shops per certificaat verstrekt

wsPassword

Webservice Wachtwoord

Verplicht, wordt door Trusted Shops per certificaat verstrekt

1.2.1.3 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. 1.2.1.4 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 = "X1234567890ABCDEFGHJKLMNOPQRSTUVW"; # 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 = "https://" . 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, $buyerEmail, $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 -10001 : echo "Cause: login failed or no valid shop found for tsId '$tsId'"; © 2015 Trusted Shops GmbH

7


break; ... } } else { echo "TS Webservice has successfully returned application number '$returnValue'"; }

1.2.1.5 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

NL

DIRECT_DEBIT

Machtiging / automatische incasso

CREDIT_CARD

Creditcard

INVOICE

Factuur

CASH_ON_DELIVERY

Onder rembours

PREPAYMENT

Vooruitbetaling / overboeking

CHEQUE

Cheque

PAYBOX

Paybox

PAYPAL

PayPal

AMAZON_PAYMENTS

Amazon Payments

CASH_ON_PICKUP

Betaling bij afhalen

FINANCING

Op afbetaling

LEASING

Leasing

T_PAY

T-Pay

CLICKANDBUY

Click&Buy

GIROPAY

Giropay

GOOGLE_CHECKOUT

Google Checkout

SHOP_CARD

Betaalkaart van de webwinkel

DIRECT_E_BANKING

SOFORT Banking

MONEYBOOKERS

moneybookers.com

DOTPAY

Dotpay

PLATNOSCI

Płatności

PRZELEWY24

Przelewy24

OTHER

Andere betalingswijze


8


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.

1.2.2.1

Omschrijving en gegevenstypes

WSDL-definitie: <message name="ApplicationRequestService_getRequestState"> <part name="tsId" type="xsd:string"/> <part name="applicationId" type="xsd:long"/> 1.2.2.2

Parameter

Parameter

Beschrijving

Commentaar

tsID

Trusted Shops ID van het certificaat

Verplicht, wordt door Trusted Shops per certificaat verstrekt; iedere taalversie en iedere afzonderlijke webwinkel in een zogenaamd “multishopsysteem” vereist een eigen certificaat

applicationID

Aanvraagnummer kopersbescherming

Verplicht, antwoord van requestForProtectionV2()

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


Afhandeling van de wachtrij

Opslag en verwerking van garantieaanvragen

Verplicht, bijvoorbeeld via retry maximaal 3 maal met een interval van 8 uur, daarna annuleren

Logboek

Registreren van garantieaanvragen, foutmeldingen, SOAP-exceptions enz.

Verplicht, bijvoorbeeld in de vorm van een log van afgesloten garanties op het dashboard van de shopbeheersomgeving

1.3.1

Foutmeldingen

Code

Antwoord

Oorzaak

-10001

NO_VALID_SHOP

Ongeldige TS-ID of login voor de webservice

-10002

LIMIT_CANCELLED

De kredietlimiet van de webwinkel is door Trusted Shops opgeheven

-10003

DUPLICATE_ORDER_NUMBER

Bestelnummer meerdere keren gebruikt

-10004

UNSUPPORTED_TS_PRODUCT

Kopersbeschermingsproduct niet ondersteund

-10005

INACTIVE_PAYMENT_TYPE

Betalingswijze niet geactiveerd

-10006

UNSUPPORTED_PAYMENT_TYPE

Betalingswijze niet ondersteund

-10007

CURRENCY_MISMATCH

De valuta van het kopersbeschermingsproduct komt niet overeen met de valuta van het winkelmandje

-10008

UNSUPPORTED_CURRENCY

De gekozen valuta wordt door deze shop niet geaccepteerd

-10009

UNSUPPORTED_EXCHANGE_RATE

De wisselkoers wordt niet ondersteund

-10010

NOT_PERSISTENT_PAYMENT_TYPE

De betalingswijze wordt niet ondersteund

-10011

NO_LIMIT

Geen kredietlimiet aanwezig voor dit certificaat

-10012

PAST_DELIVERY_DATE

De afleveringsdatum bevindt zich in het verleden

-10013

TOO_OLD_ORDER

De garantie werd aangevraagd voor een aankoop die meer dan 3 dagen geleden werd gedaan

-10014

EMAIL_MALFORMED

Het formaat van het e-mailadres is onjuist

-10015

ORDER_ID_EMPTY

Er werd geen bestelnummer meegezonden

-10016

CUSTOMER_ID_EMPTY

Er werd geen klantnummer meegezonden

-10017

LIMIT_OVERFLOW

De kredietlimiet voor dit certificaat is overschreden

-10018

EMAIL_EMPTY

Er werd geen e-mailadres meegezonden

-10019

WRONG_TS_PRODUCT

Er is een onjuist kopersbeschermingsproduct aangegeven

-10020L ORDER_DATE_FUTURE

De besteldatum ligt in de toekomst

-11001

Token ongeldig

INVALID_SECURITY_TOKEN


10


-11111

SYSTEM_EXCEPTION

Algemene systeemfout, neem a.u.b. contact op met Trusted Shops

1.3.2 Typische SOAP-exceptions Tijdens de implementatiefase en in productie kunnen SOAP-exceptions optreden. Deze typische uitzonderingsgevallen hebben de volgende oorzaken: Foutmeldingen

Oorzaak

Invalid number of payload elements: 12 Error code: env:Server

Aantal en volgorde van de verstuurde parameters controleren

java.lang.NumberFormatException

ongeldig bedrag

Date value does not follow the format ...

ongeldige datum

String index out of range: 0

lege datum

1.3.3 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):

X41495A6E65ECDDCD554A02C0601D1C97

Gebruikersnaam (wsUser): Wachtwoord (wsPassword):

1.4

testExcellencePartner test12345678

Integratie van de kopersbescherming op de homepage van de webwinkel

1.4.1 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. 1.4.2

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)


11


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 E-mailadres voor de afwikkeling van de koperbescherming door Trusted Shops. Garantievoorwaarden voor de koperbescherming. 1.4.3 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.): https://www.trustedshops.com/shop/certificate.php?shop_id=shop_id

URL-link "Opslag" (geel gemarkeerde tekst vervangen a.u.b.):" http://www.trustedshops.com/shop/data_privacy.php?shop_id=shop_id

URL Link "Trusted Shops Garantie", "Garantievoorwaarden" (geel gemarkeerde tekst vervangen a.u.b.): http://www.trustedshops.com/shop/protection_conditions.php?shop_id=shop_id

1.5 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 http://www.trustedshops.nl/trustbadge 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: http://www.trustedshops.nl/trustbadge

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: +31 020 709 1235 E-mail: [email protected]


12

Trusted Shops Integratiehandboek

Recommend Documents