Handleiding implementatie connect

Handleiding implementatie connect

Inhoudsopgave INHOUDSOPGAVE... 2 INLEIDING... 3 Beveiliging... 3 TRANSACTIE STARTEN... 5 URL s... 5 Betalingsverzoek... 5 Doorsturen... 6 TRANSACTIE VOLTOOIEN... 6 Notificatie... 6 Statusverzoek... 6 Antwoord voor consument... 6 Transactie-updates... 7 TEST GEGEVENS... 7 VOORBEELD: HTML FORMULIER... 8 Uitleg... 8 VOORBEELD: BETALINGSVERZOEK... 9 Antwoord... 9 VOORBEELD: STATUSVERZOEK... 10 Verzoek... 10 Antwoord... 10 BETAALMETHODEN OP UW WEBSITE SELECTEREN... 10 Opvragen van de gateways... 11 Antwoord... 11 APPENDIX: VELDDEFINITIES (VERZOEKEN)... 12 APPENDIX: VELDDEFINITIES (ANTWOORDEN)... 13 APPENDIX: RESULTAATCODES... 13 APPENDIX: ONDERSTEUNENDE VALUTA... 14 VRAGEN?... 14 31-3-2011 Pagina 2

Inleiding Het revolutionaire betaalplatform van MultiSafepay haalt alles uit de moderne technologie wat er in zit. MultiSafepay is een moderne, betrouwbare oplossing voor zowel de kleine als de grote webwinkel. Bovendien stelt het consumenten in staat om naar elkaar geld over te maken. Voor de webwinkels heeft MultiSafepay een implementatie handleiding ontwikkeld waardoor u direct alle geaccepteerde betaalmethodes (ideal, CreditCard, bankoverboekingen, Mister Cash, etc.) kunt accepteren. Hierdoor kunt u 24 uur per dag, 7 dagen per week alle populaire betaalmogelijkheden direct in uw webwinkel accepteren. Beveiliging Alle communicatie geïnitieerd door de webshop vindt plaats via een beveiligde verbinding. Alleen de notificaties, geïnitieerd door MultiSafepay, kunnen niet 100% gegarandeerd via een beveiligde verbinding plaatsvinden. Er worden dan ook geen gevoelige gegevens opgenomen in deze notificaties. 31-3-2011 Pagina 3

Voorafgaand aan de implementatie Voordat u aan de slag kunt met de implementatie van MultiSafepay in uw website dient u allereerst de website toe te voegen in het MultiSafepay-account. Log in uw MultiSafepay-account in en kies vervolgens voor Websites. Om een website aan uw account te kunnen koppelen dient u de volgende gegevens in te vullen: Beschrijving: de naam van de webshop zoals deze getoond wordt bij een transactie. Basis URL: de URL van uw website/webshop Categorie: de categorie waarbinnen uw website valt. Notificatie URL: een URL welke door MultiSafepay wordt gebruikt om de status van uw order te updaten. Bij gebruik van een shopmodule staat deze vermeld in de desbetreffende implementatie-handleiding. Nu inschakelen : aanvinken wanneer uw website reeds live is. PrivatePay inschakelen: met de functie Private Pay is het mogelijk om uw klanten anoniem te laten betalen. MultiSafepay garandeert uw klant dan dat u als webwinkelier geen beschikking krijgt over de persoonsgegevens. Dit is uiteraard alleen mogelijk indien u geen fysieke producten levert. 31-3-2011 Pagina 4

SecondChance inschakelen: het is erg vervelend als een klant een gestarte transactie niet afmaakt en dus zonder daadwerkelijk iets te kopen uw webwinkel verlaat. Gebruikt u de Second Chance functie, dan verstuurt MultiSafepay automatisch een betaal-link per e-mail naar uw klant, zodat deze de transactie eventueel op een ander moment kan afronden. Omschrijving voor portal: hier kunt u een omschrijving invullen welke wij zullen weergeven bij uw webshop in onze portal wanneer u dit wenst. Weergeven in portal: hier kunt u aangeven of u wilt dat uw webshop wordt getoond in de MultiSafepay-portal. QShops Keurmerk: hier kunt u aangeven of het QShops Keurmerk aan uw webshop is toegekend. Thuiswinkel Waarborg: hier kunt u aangeven of het Thuiswinkel Waarborg aan uw webshop is toegekend. AntiTrust Certificaat: hier kunt u aangeven of het AntiTrust Certificaat aan uw webshop is toegekend. Nadat u deze gegevens heeft ingevoerd klikt u op Opslaan. De website wordt nu toegevoegd aan uw account en er worden een tweetal codes gegenereerd: de Site ID en de Site Code. Deze codes (samen met het aansluitnummer) heeft u nodig voor de implementatie van MultiSafepay in uw webshop. LET OP: deze beveiligingscode is niet dezelfde als de beveiligingcode om in te loggen in de MultiSafepay-account. Transactie starten URL s Er zijn is een test omgeving en een live omgeving beschikbaar. Voor de testomgeving dient u een apart account aan te vragen. Live https://api.multisafepay.com/ewx/ Test https://testapi.multisafepay.com/ewx/ Betalingsverzoek Met een betalingsverzoek (transaction request) start u een transactie bij MultiSafepay. Alle benodigde waarden voor dit verzoek geeft u op in een XML-document. Dit document heeft als root een element met naam redirecttransaction. In het verzoek stuurt u de volgende gegevens mee: de gegevens van uw webshop in het merchant-element de gegevens van uw klant in het customer-element de gegevens van de betaling in het transaction-element handtekening in het signature-element Ieder betalingsverzoek moet voorzien zijn van een handtekening. Deze wordt gegenereerd door de waardes van de elementen transaction/amount, transaction/currency, merchant/account, merchant/site_id en transaction/id samen te voegen (in deze volgorde) en van het resultaat een MD5- hash te genereren. Voor een volledig voorbeeld; zie voorbeeld:betalingsverzoek. De server van MultiSafepay controleert het verzoek en geeft aan of de betaling is goed gekeurd. Het result-attribuut van het root-element van het antwoord geeft deze status aan. 31-3-2011 Pagina 5

Doorsturen Nadat uw betalingsverzoek is goedgekeurd stuurt u de gebruiker door naar de MultiSafepay betaalmodule door het uitvoeren van een HTTP redirect. Het adres hiervoor wordt meegestuurd in het antwoord op het betalingsverzoek (indien succesvol) en kunt u vinden in het transaction/payment_url-element. Transactie voltooien Notificatie MultiSafepay heeft 2 verschillende notificatie URL s. De eerste Notificatie URL kan door de merchant worden meegeven in de XML bij het initiëren van een transactie in de <notification_url> Deze URL wordt aangeroepen wanneer de user de betaling heeft afgerond. De transactie-update notificatie URL moet worden ingesteld bij het aanmaken van een site. Deze wordt bij iedere status wijziging van een order aangeroepen. MultiSafepay roept de URL aan zoals opgegeven in het payment_url-element. In dit verzoek wordt de transactie ID meegestuurd in de GET-variable transactionid. Het is de verantwoordelijkheid van de winkelier om de status van de betaling op te vragen. Een notificatie betekent dus niet dat een betaling succesvol is afgerond! Gebruik een statusverzoek om de status van de transactie op te vragen. U kunt de status van deze afgebroken transacties later zelf opvragen door middel van een statusverzoek. Statusverzoek Met een statusverzoek vraagt u de status van een betaling op bij MultiSafepay. Ook dit verzoek geeft u op in een XML-document. Dit document heeft als root een element met naam status. In het verzoek stuurt u de volgende gegevens mee: de gegevens van uw webshop in het merchant-element de transactie ID in het transaction/id-element De server van MultiSafepay controleert het verzoek en geeft aan of het verzoek is goed gekeurd of niet in het result-attribuut van het root-element van het antwoord. Voor een volledig voorbeeld, zie Voorbeeld: Statusverzoek. De huidige status van de betaling vindt u in het ewallet/status-element. De volgende waardes zijn mogelijk. completed: succesvol voltooid initialized: aangemaakt, maar nog niet voltooid uncleared: aangemaakt, maar nog niet vrijgesteld (credit cards) void: geannuleerd declined: afgewezen refunded: terugbetaald expired: verlopen Overige gegevens met betrekking tot de transactie kunt u ook terugvinden in het antwoord. De gegevens van de klant worden niet altijd meegestuurd in het antwoord. Zie het voorbeeld voor meer details. Antwoord voor consument Nadat u de status heeft opgevraagd kunt u een bericht voor de gebruiker genereren (HTML) en deze retourneren als antwoord op de notificatie. De HTML wordt getoond binnen de MultiSafepay betaalmodule. U kunt dit bericht bijvoorbeeld gebruiken om de gebruiker te voorzien van een link terug naar uw webshop, of om extra instructies door te geven. 31-3-2011 Pagina 6

Transactie-updates Ook als een betaling van status veranderd wordt een notificatie URL aangeroepen; dit is een andere URL en kan worden geconfigureerd bij de gegevens van uw site, nadat u ingelogd bent op de MultiSafepay website. In dit verzoek wordt de transactie ID meegestuurd in de GET-variable transactionid. Als u de notificatie correct heeft verwerkt dient u als antwoord op het verzoek de tekst OK te geven. Als er iets fout is gegaan, dan geeft u een ander antwoord als OK (bijvoorbeeld een foutmelding). Het verzoek wordt dan tot drie keer herhaald, en de melding wordt gelogd. Foutafhandeling Als er een fout optreedt, dan wordt deze gerapporteerd in een error-element. Het result-attribuut van het root element is dan gezet op error. De foutmelding bestaat uit een code en een omschrijving van de fout. De mogelijke codes zijn te vinden in Appendix: Resultaatcodes. Code 1017 is bestemd voor de bezoeker van uw website. Een suggestie voor de melding aan uw bezoeker is Onvoldoende saldo op uw MultiSafepay-account. Test gegevens Visa #4111111111111111 Goed #4012888888881881 Fout reden onvoldoende saldo #4012888888881882 Kaartnummer fout (dit kan al door middel van het kaartnummer controlescript worden afgevangen) MasterCard #5105105105105100 Goed #5555555555554444 Fout reden onvoldoende saldo Bancontact/MisterCash #67030000000000003 Giropay Rekeningnummer: 123456 Bankcode: 44448888 ideal Selecteer InternalIssuerSimulation deze doorloopt de betaling (de ideal betaling wordt niet op betaald gezet). 31-3-2011 Pagina 7

Voorbeeld: HTML formulier <form action="https://api.multisafepay.com/ewx/post.php" method="post" target="_blank"> <input type="hidden" name="currency" value="eur" /> <input type="hidden" name="action" value="pay" /> <input type="hidden" name="account" value="123456" /> <input type="hidden" name="site_id" value="789" /> <input type="hidden" name="site_secure_code" value="112233" /> <input type="hidden" name="amount" value="10.00" /> <input type="hidden" name="description" value=" Voorbeeld product" /> <input type="hidden" name="items" value="" /> <input type="submit" value= Submit name= Submit /> </form> Uitleg <form action="https://api.multisafepay.com/ewx/post.php" method="post" target="_blank"> Op dit punt worden er instructies meegegeven om de waarden te sturen naar https://api.multisafepay.com/ewx/post.php. Deze URL is alleen van toepassing bij gebruik van een live account. Maakt u gebruik van een test account, dan dient u bijgaande URL te gebruiken: https://testapi.multisafepay.com/ewx/post.php. <input type="hidden" name="currency" value="eur" /> Hiermee wordt de munteenheid van de betaling bepaald. Momenteel is het enkel mogelijk om de betaling in Euro s te doen. De waarde blijft staan op EUR. <input type="hidden" name="action" value="pay" /> De actie hier is pay. Deze waarde verandert ook niet. <input type="hidden" name="account" value="123456" /> Dit is de account ID. <input type="hidden" name="site_id" value="789" /> De Site ID wordt aangemaakt wanneer een website wordt toegevoegd in de merchant back-office. De Site ID is te zien wanneer u inlogt op uw account. <input type="hidden" name="site_secure_code" value="112233" /> De Site Secure Code wordt tevens aangemaakt wanneer u een website toevoegt. De Site Secure Code is tevens te zien wanneer u inlogt op uw account. <input type="hidden" name="amount" value="10.00" /> Hier wordt het bedrag van de betaling bepaald. Dit formulier is voor een betaling van 10 euro s. <input type="hidden" name="description" value="voorbeeld product" /> Wanneer een betaling plaatsvindt, wordt er een beschrijving getoond. <input type="hidden" name="items" value="" /> Wanneer u een formulier maakt voor meerdere items, dan kunt u deze waarde gebruiken om meerdere items toe te voegen. Hier kunt u HTML codes gebruiken zoals <ul><li>..</li></ul>. Houd u er rekening mee dat het naar ons moet worden toegestuurd. Daarbij dient < te worden aangegeven met <. <input type="submit" value= Submit name= Submit /> Dit is enkel de verstuur knop. U kunt het ook automatisch laten versturen of een image gebruiken waar op geklikt kan worden. </form> 31-3-2011 Pagina 8

Voorbeeld: Betalingsverzoek <?xml version="1.0" encoding="utf-8"?> <redirecttransaction ua= custom-1.2 > <merchant> <account>123456</account> <site_id>789</site_id> <site_secure_code>112233</site_secure_code> <notification_url>http://www.example.com/notify/</notification_url> <redirect_url>http://www.example.com/thanks/</redirect_url> <cancel_url>http://www.example.com/cancel/</cancel_url> <close_window>false</close_window> </merchant> <customer> <locale>nl_nl</locale> <ipaddress>1.2.3.4</ipaddress> <forwardedip></forwardedip> <firstname>first</firstname> <lastname>last</lastname> <address1>address</address1> <address2></address2> <housenumber>123</housenumber> <zipcode>12345</zipcode> <city>city</city> <state></state> <country>nl</country> <phone></phone> <email>example@example.com</email> </customer> <transaction> <id>abcd1234</id> <currency>eur</currency> <amount>1000</amount> <description>my Description</description> <var1></var1> <var2></var2> <var3></var3> <items>my Items</items> <manual>false</manual> <gateway></gateway> <daysactive></daysactive> </transaction> <signature>652a5f2d94d384ba3fecad57c77586e1</signature> </redirecttransaction> Antwoord <?xml version="1.0" encoding="utf-8"?> <redirecttransaction result="ok"> <transaction> <id>abcd1234</id> <payment_url>http://www.multisafepay.com/pay/ lang=en</payment_url> </transaction> </redirecttransaction> 31-3-2011 Pagina 9

Voorbeeld: Statusverzoek Verzoek <?xml version="1.0" encoding="utf-8"?> <status ua= custom-1.1 > <merchant> <account>123456</account> <site_id>789</site_id> <site_secure_code>112233</site_secure_code> </merchant> <transaction> <id>abcd1234</id> </transaction> </status> Antwoord <?xml version="1.0" encoding="utf-8"?> <status result="ok"> <ewallet> <id>12345</id> <status>completed</status> <created>20070723171623</created> <modified>20070903155907</modified> </ewallet> <customer> <currency>eur</currency> <amount>1000</amount> <exchange_rate>1</exchange_rate> <firstname>first</firstname> <lastname>last</lastname> <city>city</city> <state></state> <country>nl</country> </customer> <transaction> <id>abcd1234</id> <currency>eur</currency> <amount>1000</amount> <description>my Description</description> <var1></var1> <var2></var2> <var3></var3> <items>my Items</items> </transaction> </status> Betaalmethoden op uw website selecteren U kunt ervoor kiezen dat de klant op uw website een betaalmethode selecteert. Door middel van de getgateway functie kunt u aangeven welke beschikbare betaalmethoden voor het betreffende land getoond worden. U kunt een betaalmethode met de transactie XML meegeven in de gateway. 31-3-2011 Pagina 10

Opvragen van de gateways <?xml version="1.0" encoding="utf-8"?> <gateways ua= example-php-1.1 > <merchant> <account>123456</account> <site_id>789</site_id> site_secure_code>112233</site_secure_code> </merchant> <customer> <country>nl</country> </customer> </gateways> Antwoord <?xml version="1.0" encoding="utf-8"?> <gateways result="ok"> <gateways> <gateway> <id>ideal</id> <description>ideal</description> </gateway> <gateway> <id> MASTERCARD</id> <description>visa via Multipay</description> </gateway> <gateway> <id> BANKTRANS</id> <description> Bank Transfer</description> </gateway> <gateway> <id> VISA</id> <description> Visa CreditCardsdescription> </gateway> </gateways> </gateways> 31-3-2011 Pagina 11

Appendix: Velddefinities (verzoeken) Onderdeel Veld Waarde Lengte Omschrijving transaction id Tekst 50 Transactie ID van merchant transaction currency XYZ 3 Valutacode, zie tabel transaction amount Numeriek Bedrag in centen (Bedrag 100) transaction description Tekst Omschrijving transaction var1, var2, var3 Tekst 100 Velden voor vrij gebruik transaction items Tekst Uitgebreide omschrijving (HTML) transaction manual true / false Transactie handmatig controleren transaction gateway tekst 50 Preselected Gateway. Opvragen via gateways. transaction daysactive Numeriek Aantal dagen dat payment link actief is merchant account Numeriek Account ID merchant site_id Numeriek Site ID merchant site_secure_code Numeriek Site Security Code merchant notification_url Tekst Notificatie URL merchant cancel_url Tekst Cancel URL merchant redirect_url Tekst Redirect URL merchant close_window true / false Scherm afsluiten customer locale ab_cd 5 Taal (ISO 639) en Land (ISO 3166) customer ipaddress n.n.n.n IP-adres customer forwardedip n.n.n.n IP-adres indien via proxy customer firstname Tekst 25 Voornaam customer lastname Tekst 25 Achternaam customer address1 Tekst 64 Adresregel 1 (straatnaam) customer address2 Tekst 64 Adresregel 2 customer housenumber Tekst 10 Huisnummer customer zipcode Tekst 10 Postcode customer city Tekst 50 Stad customer country AB 2 Land (ISO 3166) customer phone Tekst 25 Telefoonnummer customer email Tekst 50 E-mailadres signature Tekst 32 MD5 hash * Vetgedrukte velden zijn verplicht in een verzoek. Indien customer/country leeg is, wordt deze bepaald aan de hand van de IP-adressen opgegeven in customer/ipaddress en customer/forwardedip. 31-3-2011 Pagina 12

Appendix: Velddefinities (antwoorden) Onderdeel Veld Waarde Lengte Omschrijving transaction id Tekst 50 Transactie ID van merchant transaction payment_url Tekst Betalings URL customer firstname Tekst 25 Voornaam (optioneel) customer lastname Tekst 25 Achternaam (optioneel) customer city Tekst 50 Stad (optioneel) customer country AB 2 Land (ISO 3166) (optioneel) customer currency XYZ 3 Valutacode, zie tabel customer amount Numeriek Bedrag in centen (Bedrag 100) customer exchange_rate Reëel Wisselkoers ewallet id Numeriek Intern transactie ID ewallet status Tekst 15 Transactiestatus ewallet created Datum Datum aanmaken transactie ewallet modified Datum Datum wijziging transactiestatus error code Numeriek Resultaatcode error description Tekst Omschrijving van foutmelding Appendix: Resultaatcodes Code Omschrijving Onderdeel Veld 0000 OK 1000 Berichttype onbekend fout XML bericht 1001 Bedrag ongeldig transaction amount 1002 Valuta ongeldig transaction currency 1003 Merchant Account ID ongeldig merchant account 1004 Merchant Site ID ongeldig merchant site_id 1005 Merchant Site Security Code ongeldig merchant site_secure_code 1006 Transactie ID ongeldig transaction id 1007 IP-adres ongeldig customer ipaddress, forwardedip 1008 Omschrijving ongeldig transaction description 1009 Gereserveerd 1010 Variabele ongeldig transaction var1, var2, var3 1011 Customer Account ID ongeldig 1012 Customer Security Code ongeldig 1013 Signature ongeldig signature 1014 Niet nader gespecificeerde fout 1015 Account onbekend 31-3-2011 Pagina 13

1016 Ontbrekende gegevens 1017 Onvoldoende saldo bestemd voor klant 1018 Gereserveerd 1019 Gereserveerd 9999 Onbekende fout Appendix: Ondersteunende valuta Code Omschrijving EUR USD GPB Euro U.S. Dollar (Nog niet beschikbaar) Engelse Pond (Nog niet beschikbaar) Vragen? Heeft u vragen tijdens de implementatie? Ons technisch support team staat voor u klaar om u te ondersteunen bij uw project. U kunt contact opnemen op werkdagen van 8.30 uur tot 17.30 uur via telefoonnummer 020 8500 500. Tevens kunt u in contact komen met ons technisch support team door gebruik te maken van de Live Chat functie op onze website. 31-3-2011 Pagina 14