Technische aansluit documentatie Versie

Transcriptie

1 Versie

2 Inhoudsopgave Wijzigingen...2 Introductie... 3 Overzicht koppeling...3 Uw site instellen... 4 Overzicht instellingen...4 Gateway koppeling... 6 Overzicht POST variabelen...6 De hash variabele...7 Voorbeeld in PHP...8 Beschikbare betaal methoden...8 Test transacties...9 Terugkoppeling De 'hash' variabele in de terugkoppeling PHP voorbeeld verificatie 'hash' variabele in terugkoppeling Uw response Aandachts punten Dubbele terugkoppeling Volgorde terugkoppeling Unieke referentie Specifieke opties: ideal Overzicht banken Status codes Meer informatie Wijzigingen Datum Naam Versie Opmerkingen BZ 2.00 Initiële versie BZ 2.10 Aanpassingen test modus Nieuwe betaal methoden BZ 2.11 Aanpassing 'Omschrijving op betaal pagina' BZ 2.20 Toevoeging hash controle terugkoppeling Toevoeging directe aanroep ideal banken BZ 2.21 Wijziging Overzicht banken Wijziging hash controle terugkoppeling (test) BZ 2.22 Kleine textuele fouten opgelost BZ 2.23 Triodos Bank toegevoegd bij ideal Pagina 2 van 16

3 Introductie Deze documentatie heeft als doel u te begeleiden bij de koppeling van uw website met de gateway van Card Gate Plus. Wij raden u aan deze documentatie eerst volledig te lezen, alvorens u aan de slag gaat met het maken van de koppeling. De gateway is een simpele, enkele koppeling welke uw site voorziet van meerdere betaal methoden. Voor meer informatie over de aangeboden betaal methoden verwijzen wij u graag naar onze website of onze verkoop afdeling. Overzicht koppeling Onderstaande overzicht geeft aan welke stappen u moet volgen om uw systeem te koppelen aan de gateway: Stap U doet dit Card Gate Plus doet dit Account aanmaken en verifieren Kennis maken met het Merchant control panel Uw site instellen De koppeling tot stand brengen De terugkoppeling verwerken Uw site actief zetten Indien u nog geen login gegevens heeft en u bent nog niet bekend met de werking van het Merchant control panel, dan verzoeken wij u om contact met ons op te nemen. De overige stappen worden in dit document beschreven. Pagina 3 van 16

4 Uw site instellen Om een correcte koppeling met de gateway te realiseren, dient u in het merchant control panel een aantal instellingen te maken. Door te klikken op Sites in het menu aan de bovenkant van het merchant control panel, komt u op een pagina waar een overzicht staat van uw sites. Bij iedere site staat het Site ID vermeld. Dit ID nummer heeft u nodig voor de koppeling met de gateway. Door op het icoontje voor Bewerken ( instellingen kunt maken. )te klikken, komt u op de pagina waar u de Overzicht instellingen In onderstaande tabel vindt u een overzicht van de instellingen. Instelling Type Omschrijving Site gegevens Korte omschrijving Niet instelbaar Deze korte omschrijving is ingesteld door Card Gate Plus en zal getoond worden in uw statistieken. Voor wijzigingen aan deze naam dient u contact met ons op te nemen. Site URL Niet instelbaar De URL van uw site is niet aanpasbaar. Indien u betalingen wilt accepteren op een andere URL, dient u een nieuwe site aan te laten maken. Omschrijving op betaal pagina Configuratie site Optioneel Deze omschrijving zal getoond worden op de betaal pagina's. Voor betaal methoden waar dit toegestaan is, bijvoorbeeld ideal, zal deze omschrijving ook getoond worden op het afschrift van de klant. Control URL Optioneel Indien er een transactie heeft plaats gevonden, stuurt onze server een terugkoppeling naar uw site. Deze terugkoppeling is niet zichtbaar voor uw klant. Return URL Optioneel Uw klant wordt teruggestuurd naar deze URL na het doen van een succesvolle transactie. Return URL failed Optioneel Uw klant wordt teruggestuurd naar deze URL na het doen van een mislukte transactie. Configuratie test omgeving Control URL Optioneel Indien deze URL is ingevuld, zal onze server een terugkoppeling aan uw site sturen nadat er een test transactie heeft plaats gevonden. Pagina 4 van 16

5 Return URL Optioneel Indien er een Control URL is ingevuld onder Configuratie test omgeving, zal u na een succesvolle transactie doorgestuurd worden naar deze URL. Return URL failed Optioneel Indien er een Control URL is ingevuld onder Configuratie test omgeving, zal u na een mislukte transactie doorgestuurd worden naar deze URL. Instellingen design URL afbeelding header Optioneel U kunt hier de locatie van een plaatje opgeven. Indien dit veld is ingevuld, zal de header op de betaal pagina vervangen worden door het plaatje op deze URL. Let op! Staat uw afbeelding niet op een site met een SSL certificaat, neemt u dan contact met ons op. Wij plaatsen de afbeelding dan op onze beveiligde server. Zo voorkomt u dat gebruikers een beveiligings waarschuwing kunnen krijgen. Achtergrond kleur Optioneel Indien u dit veld invult, krijgt de betaal pagina deze achtergrond kleur. Dit veld verwacht een hexadecimale waarde als invoer, zonder het #- teken. Bijvoorbeeld FFFFFF voor wit. Kleur randen Optioneel Indien u dit veld invult, worden de randen op de betaal pagina in deze kleur getoond. Dit veld verwacht een hexadecimale waarde als invoer, zonder het #-teken. Beveiligings instellingen Bijvoorbeeld voor zwart. Codeer sleutel Verplicht De codeer sleutel zal gebruikt worden om uw opdrachten tot het doen van een transactie te versleutelen. Dit veld bestaat uit maximaal acht karakters. Pagina 5 van 16

6 Gateway koppeling De gateway verwacht dat u uw klant naar de gateway URL stuurt, voorzien van een aantal variabelen. Deze variabelen moeten via een POST gestuurd worden. De gateway URL is Overzicht POST variabelen In onderstaand overzicht ziet u welke variabelen u mee dient te sturen en welke optionele variabelen u mee kunt sturen. Naam Type Verplicht Omschrijving test Integer Optioneel Met deze variabele kunt u een test transactie uitvoeren. Geldige waarden zijn 0 en 1. option String Optioneel Indien er meerdere betaal methoden voor uw site geactiveerd zijn, kunt u het keuze scherm overslaan door aan te geven welke betaal methode getoond moet worden. Een overzicht van de mogelijke waarden kunt u vinden onder Beschikbare betaal methoden suboption String Optioneel Bij sommige betaal methoden kan een sub optie meegestuurd worden, bijvoorbeeld de bank keuze voor ideal. siteid Integer Verplicht Het ID van uw site. Dit ID staat vermeld in het merchant control panel onder Sites. currency String Optioneel De valuta waarin de transactie plaats dient te vinden. Indien u een valuta opgeeft welke anders is dan de standaard valuta van uw account, zal de gateway proberen een conversie te maken. Exact 3 karakters, bijvoorbeeld EUR of USD. Indien u gebruik wilt maken van deze mogelijkheid, neemt u dan contact op met ons. amount Integer Verplicht Het bedrag van de transactie in centen. Indien de klant tien euro moet afrekenen, stuurt u de waarde ref String Verplicht Uw unieke kenmerk voor de transactie. Pagina 6 van 16

7 Maximaal 128 karakters. description String Optioneel Omschrijving van de transactie. Deze zal op de betaal pagina worden getoond. Maximaal 32 karakters. return_url String Optioneel Hiermee kunt u de Return URL welke bij de instellingen van uw site is ingesteld, overschrijven voor de huidige transactie. return_url_failed String Optioneel Hiermee kunt u de Return URL failed welke bij de instellingen van uw site is ingesteld, overschrijven voor de huidige transactie. first_name String Optioneel De voornaam van uw klant. Maximaal 48 karakters. last_name String Optioneel De achternaam van uw klant. Maximaal 48 karakters. address String Optioneel Het adres van uw klant. Maximaal 48 karakters. postal_code String Optioneel De postcode van uw klant. Maximaal 48 karakters. city String Optioneel De woonplaats van uw klant. Maximaal 48 karakters. country_code String Optioneel De twee letterige land code van uw klant volgens ISO Exact 2 karakters, bijvoorbeeld NL voor Nederland of DE voor Duitsland. hash String Verplicht Een code welke gegenereerd is met behulp van de codeer sleutel. Exact 32 karakters. De hash variabele Om meer zekerheid te hebben dat de transacties welke op onze gateway aangeboden worden, van onze merchants zijn, dienen alle aanroepen de hash variabele mee te sturen. Pagina 7 van 16

8 Deze hash variabele is een MD5 versleuteling van een aantal waarden, namelijk: siteid, amount, ref en de door u ingestelde codeer sleutel. De door u ingestelde codeer sleutel is, als het goed is, alleen bekend bij u en ons. U kunt deze sleutel op ieder gewenst moment wijzigen. Bij het ontvangen van de POST variabelen, rekent de gateway de hash waarde uit. Indien de hash waarde niet overeenkomt met de door de gateway ontvangen hash variabele, verschijnt de volgende melding op de gateway: [merchant error] unauthorized access Doet u dit in test modus, dan staat de juiste hash vermeld achter deze tekst. Om te voorkomen dat een kwaadwillende bezoeker de hash kan berekenen door een transactie als test naar de gateway te sturen, dient bij een test transactie de tekst TEST voor de andere variabelen geplaatst te worden. Zo ontstaan twee verschillende uitkomsten. Voorbeeld in PHP In de programmeer taal PHP kunt u de hash op de volgende manier genereren: $hashkey = abcdefgh ; $hash = md5($siteid. $amount. $ref. $hashkey); Voor een test transactie genereert u de hash als volgt: $hashkey = abcdefgh ; $hash = md5( TEST. $siteid. $amount. $ref. $hashkey); Beschikbare betaal methoden Momenteel zijn de volgende betaal methoden beschikbaar: Betaal methode Waarde Beschikbaarheid Credit card creditcard Wereldwijd DIRECTebanking directebanking AT,BE,CH,DE ideal ideal NL Mister Cash mistercash BE PayPal Express paypal Wereldwijd Webmoney webmoney BY, RU, UA De Waarde kan als variabele option worden meegestuurd in de aanroep naar de gateway. Pagina 8 van 16

9 Test transacties Om een test transactie uit te voeren, dient u de variabele test met de waarde 1 mee te sturen naar de gateway. Denkt u hierbij aan de extra variabele voor de berekening van de hash. U dient er rekening mee te houden dat er momenteel alleen voor credit card transacties een test modus is. Indien u bij het testen van de koppeling de variabele option meestuurt met een andere waarde dan creditcard, kunt u een foutmelding krijgen. De variabele option is geen verplichte variabele. U kunt deze dus weglaten. Uw test transactie is succesvol als u een transactie van minder dan 100 euro verwerkt. Alle transacties welke gelijk zijn aan 100 euro, of groter dan 100 euro, mislukken. Om te testen, kunt u de volgende gegevens gebruiken: Kaart type VISA Kaart houder Zelf te kiezen Kaart nummer CVC Drie cijfers naar keuze Verval datum Datum in de toekomst Wij verzoeken u geen echte kaart nummers te gebruiken om een transactie te testen. Pagina 9 van 16

10 Terugkoppeling Nadat de transactie is aangeboden aan de gateway, kan uw klant de transactie afronden. Na iedere transactie, ongeacht of deze lukt of mislukt, roept de gateway de door u ingestelde Control URL aan. De Control URL wordt aangeroepen met een aantal POST variabelen, namelijk: Naam Type Omschrijving transactionid Integer Dit is het transactie ID van Card Gate Plus. is_test Integer Geeft aan of de transactie is uitgevoerd in test modus ( 1 ) of live modus ( 0 ). ref String Uw unieke kenmerk voor deze transactie. De variabele transactionid zal gelijk zijn voor alle transacties met dezelfde ref. status Integer Een numerieke status code. Meer informatie over de status codes staat verder op in dit document onder Status codes. currency String De drie letterige valuta code, bijvoorbeeld EUR voor Euro s en GBP voor Engelse Ponden. amount Integer Het bedrag van de transactie in centen. billing_option String De door uw klant gebruikte betaal methode. De mogelijke waarden kunt u vinden in dit document onder Beschikbare betaal methoden. transaction_fee Integer De totale transactie kosten welke aan u in rekening worden gebracht. Dit is een optelsom van de transaction_fee_bank en transaction_fee_cgp. transaction_fee_bank Integer De transactie kosten welke rechtstreeks door de bank aan u in rekening worden gebracht. transaction_fee_cgp Integer De transactie kosten welke door Card Gate Plus aan u in rekening worden gebracht. customer_firstname String De voornaam van uw klant (optioneel). customer_lastname String De achternaam van uw klant (optioneel). customer_company String De bedrijfsnaam van uw klant (optioneel). customer_address String Het adres van uw klant (optioneel). customer_zipcode String De postcode van uw klant (optioneel). customer_countrycode String De twee cijferige land code van uw klant (optioneel). customer_phonenumber String Het telefoon nummer van uw klant (optioneel). customer_ String Het adres van uw klant (optioneel). customer_ip_address String Het IP adres van uw klant. card_type String Het type kaart dat gebruikt is door uw klant (optioneel). Pagina 10 van 16

11 cardnumber_masked String Het kaart nummer van uw klant (optioneel). Vanwege veiligheids restricties krijgt u alleen de eerste zes en de laatste vier cijfers van het kaart nummer. card_expirydate String De verval datum van de kaart van uw klant (optioneel). threed_secure String Geeft aan of uw klant gebruik gemaakt heeft van 3D secure voor het voltooien van de transactie. Geldige waarden zijn: Y Ja N Nee U Onbekend E Er is een fout opgetreden Voor meer informatie over 3D secure verwijzen wij u naar onze verkoop afdeling. hash String Om de terugkoppeling te verifieren, sturen wij een 'hash' variabele mee terug. Meer over de opbouw van deze 'hash' variabele kunt u hieronder lezen. De 'hash' variabele in de terugkoppeling Om meer zekerheid te hebben dat de terugkoppeling van Card Gate Plus afkomstig is, worden alle aanroepen naar de 'Control URL' voorzien van een 'hash' variabele. Deze hash variabele is een MD5 versleuteling van een aantal waarden, namelijk: 'transaction_id', 'currency', 'amount', 'ref', 'status' en de door u ingestelde codeer sleutel. De door u ingestelde codeer sleutel is, als het goed is, alleen bekend bij u en ons. U kunt deze sleutel op ieder gewenst moment wijzigen. Bij een test transactie dient u voor de hash berekening de tekst TEST te plaatsen, net als bij het aanroepen van onze gateway. PHP voorbeeld verificatie 'hash' variabele in terugkoppeling In de programmeer taal PHP kunt u de hash op de volgende manier controleren: $hashkey = 'abcdefgh'; $hashverify = md5($_post['transactionid']. $currency. $amount. $ref. $_POST['status']. $hashkey); if ( $hashverify == $_POST['hash'] ) { // Transaction OK exit($_post['transactionid']. '.'. $_POST['status']); } else { // Transaction not OK exit($_post['transactionid']. '.'. $_POST['status']); } Pagina 11 van 16

12 Voor een test transactie controleert u de hash in de terugkoppeling als volgt: $hashkey = 'abcdefgh'; $hashverify = md5('test'. $_POST['transactionid']. $currency. $amount. $ref. $_POST['status']. $hashkey); if ( $hashverify == $_POST['hash'] ) { // Transaction OK exit($_post['transactionid']. '.'. $_POST['status']); } else { // Transaction not OK exit($_post['transactionid']. '.'. $_POST['status']); } Uw response De gateway verwacht dat u het Card Gate Plus transactie ID en de status code toont als body van de Control URL, bijvoorbeeld: Hierbij is het transactie ID en 200 de status code. Tussen deze twee waarden staat een punt. Aandachts punten Bij het verwerken van de terugkoppeling, dient u rekening te houden met onderstaande: Dubbele terugkoppeling Het kan zijn dat een terugkoppeling van onze gateway meerdere malen verstuurd wordt. Hoewel het weinig voorkomt, zou het vervelend zijn als u een dubbele terugkoppeling opnieuw verwerkt als transactie. Omdat iedere transactie voorzien is van uw unieke referentie (de ref variabele) kunt u aan uw kant controleren of de transactie al verwerkt is. Indien u nogmaals dezelfde referentie ontvangt met dezelfde status code, kunt u de terugkoppeling negeren. Bovenstaande is alleen van toepassing op succesvolle transacties. Voor mislukte transacties kunt u meerdere terugkoppelingen krijgen. Volgorde terugkoppeling Het kan zijn dat onze gateway eerst een status 200 ( Transactie succesvol ) verzend en daarna een status 300 ( Transactie mislukt ). Een status 200 is echter altijd definitief. U kunt er zeker van zijn dat de transactie succesvol is verwerkt. Pagina 12 van 16

13 Unieke referentie De unieke referentie is uniek in zowel de test modus als in de live modus. U kunt dus na het testen uw unieke referentie resetten. Pagina 13 van 16

14 Specifieke opties: ideal Bij de betaal methode ideal is het mogelijk om direct vanaf uw betaal pagina naar de website van de bank te gaan. Hiervoor kunt u gebruik maken van de variabele 'suboption' bij de aanroep van de gateway. De variabele 'suboption' heeft als waarde een getal. Dit getal, inclusief voorloop nullen, is gekoppeld aan een bank. Overzicht banken Het is nog niet mogelijk om de lijst met banken automatisch op te halen. Tot dit wel mogelijk is, kunt u gebruik maken van onderstaande lijst: Bank code Naam bank 0031 ABN Amro 0091 Friesland Bank 0721 ING Bank 0021 Rabobank 0751 SNS Bank 0761 ASN Bank 0771 SNS Regio Bank 0511 Triodos Bank 0161 Van Lanschot Bank Pagina 14 van 16

15 Status codes Hieronder treft u een overzicht aan van de status codes welke momenteel gebruikt worden door de gateway van Card Gate Plus. Status code Omschrijving 0 Transactie wordt uitgevoerd 100 Authorisatie succesvol 150 3D secure status Y (ja), wachten op 3D secure verificatie 152 3D secure status N (nee) 154 3D secure status U (onbekend) 156 3D secure status E (fout) 200 Transactie succesvol 210 Repeterende transactie succesvol 300 Transactie mislukt 301 Transactie mislukt door anti-fraude systeem 310 Repeterende transactie mislukt 350 Transactie mislukt, time out van 3D secure verificatie 400 Refund aan klant 410 Chargeback door klant 700 Transactie wacht op klant Pagina 15 van 16

16 Meer informatie Mocht u na het lezen van deze documentatie nog vragen hebben, neemt u dan contact met ons op. Ook voor het melden van onjuistheden in deze documentatie verzoeken wij u contact op te nemen met ons. U kunt ons bereiken via op het adres support@cardgate.com of telefonisch op nummer Pagina 16 van 16