Deze blog beschrijft de werking van exchange calls en de oplossingen voor fouten hiervan. Heeft u last van trage exchange Calls? Lees de verdieping voor gevorderde ontwikkelaars.
Vrijwel dagelijks ontvangt ons supportteam de volgende vraag: "Ik heb een email van jullie ontvangen over een mislukte exchange call, is de betaling nu wel gelukt?"
De hoogste tijd dus om dit proces eens toe te lichten door middel van een blogartikel.
1. Wat is een exchange call
Om de werking van een exchange call te kunnen begrijpen is het noodzakelijk om eerst uit te leggen wat een exchange call precies is. Een exchange call is een signaal van Pay.nl naar uw webshop om aan te geven dat een order een nieuwe status heeft gekregen. De webshop kan vervolgens de betreffende order updaten zodat de status overeenkomt met de status in het Pay.nl Admin Panel. Vanzelfsprekend is dit proces van groot belang. U kunt zich waarschijnlijk voorstellen dat er problemen ontstaan als een order in het Pay.nl Admin Panel de status 'betaald' heeft, terwijl de status in de backoffice van uw shop nog op 'open / pending' staat.
Het signaal dat Pay.nl aan uw webshop geeft is feitelijk een script (url) dat wij aanroepen op uw server. Als Pay.nl het juiste antwoord van dit script terugkrijgt weten wij dat de nieuwe orderstatus correct door uw systeem is verwerkt. Het script dat wordt aangeroepen door Pay.nl noemen wij de communicatie- of exchange URL.
2. Wanneer wordt een exchange call uitgevoerd?
In vrijwel alle gevallen zult u te maken hebben met één van de volgende drie exchange calls:
Starten van een transactie
Nadat een klant de gewenste betaalmethode heeft gekozen wordt de transactie gestart. Dit is (vaak) de eerste keer dat er een exchange call plaats vindt tussen Pay.nl en uw webshop. De order krijgt in dit geval de status: pending
Betaalde transactie
Als de transactie succesvol door uw klant is afgerond stuurt Pay.nl een exchange call met de status paid Via de exchange call wordt de order verwerkt in uw systeem en wordt er bijvoorbeeld een factuur en bevestigingsemail naar de klant verstuurd.
Geannuleerde of expired transactie
Als de betaling door de klant wordt geannuleerd dan ontvangt u direct een exchange call met de status cancel. Indien het betaalscherm echter wordt weggeklikt dan kan dit niet door Pay.nl worden geregistreerd. Ook in dit geval ontvangt u van ons de status cancel als de betaling verlopen (expired) is, meestal 4 uur nadat de transactie is gestart.
Zijn dit alle exchange calls?
Zeker niet, maar dit zijn wel de exchange calls die in 90% van de gevallen worden uitgevoerd. Betaalmethoden als incasso en creditcard hebben nog wat extra exchange calls maar deze laten we voor nu even buiten beschouwing.
3. Het instellen van een communicatie URL
Om verbinding met uw server te kunnen maken moet Pay.nl vanzelfsprekend weten welke URL er aangeroepen dient te worden. Deze communicatie URL kunt u heel eenvoudig invoeren via het Pay.nl Admin Panel.
Ga hiervoor naar het Pay.nl Admin Panel en kies bovenin het menu het tabblad Beheren -> Diensten. In het overzicht kiest u de dienst waarvoor u de communicatie URL wilt instellen door op de link 'wijzigen' te klikken van de betreffende dienst. Bij het veld 'Exchange instellen' selecteert u één van de twee onderstaande opties:
Ja, via de API of plugin meegegeven
Maakt u gebruik van een plugin of hosted solution die door Pay.nl is ontwikkeld, bv voor Magento, WooCommerce of Shoptrader dan selecteert u deze waarde. De plugin zorgt er automatisch voor dat de correcte communicatie URL wordt ingesteld. U dient de waarde 'Ja, via de API of plugin meegegeven' tevens te selecteren als u gebruik maakt van onze API's / SDK's en u de communicatie URL al mee geeft tijdens het starten van een transactie.
Ja, een custom communicatie URL gebruiken
Als de communicatie URL niet wordt ingesteld door een plugin, hosted solution of API dan dient u deze zelf in te voeren. Selecteer hiervoor de optie 'Ja, een custom communicatie URL gebruiken'. Voer vervolgens bij het veld 'Communicatie URL' de URL naar uw exchange-script in en selecteer een methode van aanroepen (GET of POST). De werking van het veld 'Aanroep herhalen' wordt in '4. Retry scheme' toegelicht.
Als uw software via de API een exchange doorgeeft én u stelt er via de dienst ook één in, dan worden ze beide aangeroepen.
4. Retry scheme
Als Pay.nl na een status verandering uw communicatie URL aanroept, dan wordt er maximaal 5 seconden gewacht op een antwoord. Het kan echter voorkomen dat uw server net op dat moment even niet bereikbaar is, of dat er allerlei zware processen lopen zodat er niet op tijd geantwoord wordt.
In dit geval verbreken wij de exchange call en beschouwen wij het verzoek als mislukt. Dit kan betekenen dat uw server de statusverandering niet (correct) heeft verwerkt en dat de orderstatus die u in uw eigen backoffice heeft staan niet overeenkomt met de status in het Admin Panel van Pay.nl!
Gelukkig is er de mogelijkheid om gebruik te maken van een 'retry scheme'. Dit zorgt ervoor dat de exchange call op en later moment nog een (aantal) keer wordt uitgevoerd tot wij een correct antwoord hebben ontvangen. Bij een retry scheme kunt u o.a het maximaal aantal herhalingen invoeren. Als dit aantal is bereikt en uw script heeft nog niet het vereiste antwoord gegeven dan sturen wij u een notificatie per email. Pay.nl adviseert iedere merchant om gebruik te maken van een retry scheme, u stelt deze als volgt in:
In het screenshot hiernaast zien we dat de order om 17:55 is gestart, de bijbehorende exchange call met status pending is correct uitgevoerd. Ruim 2 minuten laten heeft de klant de betaling voltooid en probeert Pay.nl dit te communiceren middels de status new_ppt. Deze exchange call mislukt echter waardoor het retry scheme in werking treedt.
In het screenshot zien we dat het retry scheme ervoor zorgt dat 30 seconden later opnieuw de mislukte exchange call wordt uitgevoerd. Dit keer heeft Pay.nl het vereiste antwoord wel teruggekregen en wordt de exchange call als geslaagd beschouwd.
5. Resultaten exchange calls
De resultaten van een exchange calls kunt u op twee plaatsen terug vinden, via de transactiedetails en via de 'payment state log'. Geslaagde exchange calls worden voorzien van het volgende icoon , mislukte verzoeken worden weergegeven via het icoon .
Transactiedetails
Om de exchange verzoeken van één transactie te bekijken voert u de onderstaande stappen uit:
- In het Admin Panel kiest u in het menu de optie Beheren -> Transacties.
- Zoek de transactie op waarvan u de exchange verzoeken wilt bekijken.
- Klik op de EX-code of het vergrootglas-icoon van de transactie. Er wordt een popup geopend waar u alle details van de betreffende transactie vindt.
- Onderaan de popup, bij 'Communicatie informatie', ziet u de resultaten van de exchange verzoeken die voor deze transactie zijn uitgevoerd.
Payment state log
Het 'Payment state log' is een overzicht van alle exchange verzoeken tussen Pay.nl en uw server. U vindt dit overzicht via het Admin Panel menu: Rapportages -> Payment state log.
U kunt via het de link 'Configuratie' rechtsonder het menu extra kolommen activeren zodat u meer informatie over de exchange call krijgt. Via de link in de kolom 'Opties' verkrijgt u alle details van de transactie, inclusief de aangeroepen URL en het volledige antwoord dat wij van uw server hebben ontvangen.
Als u enkel de exchange calls van één transactie wilt weergegeven dan kunt u bovenin de pagina zoeken op 'Betaalsessie ID'. Het betaalsessie ID van een order vindt u in het transactieoverzicht.
Instructiefilm exchange verzoeken
Is na het lezen van deze blogpost de werking van een exchange call u nog niet helemaal duidelijk? Of wilt u alle informatie nog een keer rustig bekijken?
In deze 4 minuten durende instructiefilm worden de bovenstaande vijf punten nogmaals stap voor stap uitgelegd.
6. Checklist: hoe voorkom ik een mislukte exchange call.
Om terug te komen op de vraag uit de eerste paragraaf: "Ik heb een email van jullie ontvangen over een mislukte exchange call, is de betaling nu wel gelukt?".
Ik hoop dat u na het lezen van dit blogartikel enigszins begrijpt dat deze 2 dingen los van elkaar staan. Een betaling door een klant kan dus geslaagd zijn terwijl de bijbehorende exchange call vervolgens is mislukt. De vraag die ongetwijfeld bij u naar boven komt is: "Hoe voorkom ik dat ik emails ontvang over een mislukte exchange call?". We hebben daarom een checkist ontwikkeld waarmee u de meest voorkomende problemen kunt oplossen
1. Controleer of het retry scheme ingesteld staat
- Selecteer in het menu van het Admin Panel: Beheren -> Diensten
- Klik op de link wijzigen van een dienst
- Staat bij Communicatie URL's de optie 'Aanroep herhalen' niet aangevinkt?
Oplossing:
Zorg ervoor dat de optie 'Aanroep herhalen' aangevinkt is en selecteer binnen welke tijd u de aanroep wilt herhalen. 6 keer binnen 2 uur is voor veel webshops de aanbevolen instelling. Dit zorgt ervoor dat een mislukte exchange call op een later moment nog maximaal 6 keer wordt uitgevoerd.
2. Is er een timeout opgetreden?
- Selecteer in het Admin Panel menu: Rapportages -> Payment state log
- Controleer de waarden in de kolommen verbindinstijd en data. Ziet u deze kolommen niet? Dan kunt u deze activeren via de link 'configuratie' rechtsonder het menu.
- is de verbindstijd groter dan 5 seconden en bevat het veld data de melding 'operation timed out'?
Oplossing:
Pay.nl wacht maximaal 5 seconden op een antwoord van uw server. Als wij binnen deze tijd geen antwoord ontvangen verbreken wij de verbinding en beschouwen wij de exchange call als mislukt (timeout). Dit wil overigens niet zeggen dat de exchange call niet door uw server is verwerkt, het kan zijn dat uw server op dat moment druk was met het verwerken van een order en bijvoorbeeld pas na 6 seconden een antwoord gaf. Het instellen van een retry scheme is daarom ook vrijwel altijd de oplossing zodat het verzoek op een rustiger moment nog een keer wordt uitgevoerd.
3. Controleer de HTTP Code van de aanroep
- Selecteer in het Admin Panel menu: Rapportages -> Payment state log
- Controleer de waarden in de kolom HTTP code. Ziet u de kolom HTTP Code niet? Dan kunt u deze activeren via de link 'configuratie' rechtsonder het menu.
- Is de waarde in de kolom HTTP code niet gelijk aan
200(OK)?
Oplossing: Als de HTTP code niet gelijk aan 200 is dan heeft Pay.nl geen correcte verbinding tot stand kunnen brengen met het communicatie URL op uw server. Door op de link 'details' te klikken van de betreffende exchange call wordt een popup geopend waar u bij 'aanroep URL' de exact aangeroepen communicatie URL terugvindt. Afhankelijk van de HTTP code zijn er de volgende oplossingen:
- Status code:
0- host niet gevonden
Pay.nl heeft geen verbinding kunnen maken met uw server, vaak vindt u in het veld data de melding 'couldn't resolve host' of 'operation timed out'. Controleer of u de 'aanroep URL' de juiste domeinnaam bevat en of er geen timeout is opgetreden. De melding komt ook vaak voor als er een localhost of andere dev-URL als communicatie URL wordt gebruikt. - Status code:
301302- redirect
Er heeft een redirect plaatsgevonden waardoor Pay.nl het antwoord van de communicatie niet heeft kunnen achterhalen. Vaak wordt deze geforceerd door een .htaccess bestand. Denk bijvoorbeeld aan een redirect van http naar https of van domein.nl naar www.domein.nl. Als u de 'aanroep URL' uitvoert in een browser zult u merken dat er een redirect plaatsvindt. - Status code:
401403- verboden toegang
Pay.nl heeft geen toegang tot de beveiligde communicatie URL. In het geval van een statuscode401betekent dit vaak dat er een gebruikersnaam en wachtwoord ingevoerd dient te worden. Bij een statuscode403wordt op serverniveau de toegang tot de URL ontzegd. - Status code:
404- niet gevonden
De communicatie URL verwijst naar een URL die niet (meer) bestaat. U kunt dit controleren door de 'aanroep URL' uit te voeren in een browser. Het aanpassen van de communicatie URL zou dit probleem moeten verhelpen. - Status code:
500- interne serverfout
Er is een fout opgetreden tijdens het uitvoeren van een script of de .htaccess op de communicatie URL.
4. Is het juiste antwoord naar ons verstuurd?
- Selecteer in het Admin Panel menu: Rapportages -> Payment state log
- Controleer de waarden in de kolom 'Data', deze kolom bevat het resultaat van een exchange verzoek. Ziet u deze kolom niet? Dan kunt u deze activeren via de link 'configuratie' rechtsonder het menu.
- Is het eerste woord dat wordt weergegeven anders dan TRUE?
Oplossing:
Zodra Pay.nl het woord TRUE als resultaat terug krijgt dan beschouwen wij de exchange call als geslaagd. Alle andere output resulteert in een mislukte aanroep. Heeft u zelf het script ontwikkeld dat wordt uitgevoerd middels de exchange call? Zorg er dan voor dat de eerste 4 tekens van het resultaat gelijk zijn aan TRUE (eventueel gevolgd door een pipeline met (debug)informatie). Als u gebruik maakt van een plugin die door Pay.nl is ontwikkeld dan zou het bovenstaande automatisch geregeld moeten zijn. Neem contact met ons op indien dit niet het geval is.
Heeft u de bovenstaande 4 stappen doorlopen en is het probleem nog steeds niet opgelost? Neem dan contact op met ons technisch support team via email, chat of telefoon.