Wij gebruiken cookies om er voor te zorgen dat wij u de beste gebruikerservaring kunnen bieden op deze website. Als u verdergaat zonder uw instellingen te wijzigingen, gaan wij ervan uit dat u akkoord gaat met het ontvangen van alle cookies op de Buckaroo website. Als u dat wenst, kan u uw cookie instellingen op elk moment wijzigen. Meer informatie
Dit bericht niet meer tonen
Beste Payment Service Provider van 2014, 2015 én 2016

NVP Koppeling

De afkorting NVP staat voor "Name-Value Pair". NVP is een webservice die requests accepteert die als HTTP form post zijn opgemaakt. NVP ondersteunt alleen POST waardes. Het antwoord van de gateway is op een soortgelijke manier geformatteerd. Het antwoord ziet er als volgt uit:

prefix_fieldname=fieldvalue

Elke waarde is URL-encoded en gescheiden door een ampersand (&). Een voorbeeld ziet er als volgt uit:

BRQ_AMOUNT=12.55&BRQ_DESCRIPTION=test+description

Om het antwoord te kunnen parsen kan de response gesplitst worden op de ampersand (&). Dit maakt een lijst van Name-Value pairs. Vervolgens kan elk paar gesplitst worden op het (eerste) is gelijkteken (=). Dit resulteert in 2 waarden:

Voordat de digitale handtekening berekend wordt, moet de waarde eerst gedecodeerd worden.

Berichten naar de gateway moeten in UTF-8 encoding zijn opgemaakt. Het antwoord wordt ook in UTF-8 opgemaakt. Parameter namen zijn niet hoofdletter gevoelig. Dit geldt voor zowel het request als de response.

In het antwoord van de gateway wordt het veld BRQ_APIRESULT toegevoegd om het resultaat van aanroep terug te koppelen. Indien er iets fout gaat, wordt een veld toegevoegd met extra informatie: BRQ_APIERRORMESSAGE

BRQ_APIRESULT kan de volgende waardes bevatten:

Waarde Omschrijving
Success De actie en/of transactie is succesvol.
Reject De actie en/of transactie is afgewezen door Buckaroo of een acquirer.
Cancel De actie en/of transactie is geannuleerd.
Fail De actie en/of transactie is mislukt.
Pending De actie en/of transactie is wachtende (de uiteindelijke status zal spoedig beschikbaar zijn).
ActionRequired Er moet een actie worden uitgevoerd voordat de transactie voltooid kan worden (Bijv. een redirect).
Waiting De transactie wacht op de klant (we weten niet of er nog een andere status volgt).
OnHold De transactie is in wachtstand gezet, omdat er een reden is om niet door te gaan met de transactie. Deze status is echter niet definitief. Bijv. bij onvoldoende saldo op een refund.

Een belangrijke opmerking moet worden gemaakt over de NVP gateway. De NVP gateway ondersteunt de toevoeging van extra input- en returnfields. Dit betekent dat, zolang de bestaande berichten nog steeds geaccepteerd worden door een operation, het is toegestaan ​​om de specificatie van de operation te veranderen. Dit zijn NIET-brekende wijzigingen, waarvan hieronder de mogelijkheden:

De nieuwe NVP gateway zal gebruik maken van deze functies wanneer dat nodig is. Houdt hier rekening mee tijdens het implementeren!

Security

De NVP gateway maakt gebruik van twee lagen beveiliging. Aan de een ene kant wordt al het verkeer van en naar de gateway beveiligd met een SSL certificaat. Dit versleutelt de berichten die worden uitgewisseld over het internet. Hierdoor kunnen kwaadwillende derden deze berichten niet uitlezen. Additioneel, vereisen we dat alle verzoeken digitaal ondertekend worden. Dit geeft ons de mogelijkheid om zowel de identiteit ven de verzender te controleren als dat we kunnen controleren dat het bericht niet aangepast is. Voor het ondertekenen van het verzoek gebruiken we een vooraf gedeelde geheime sleutel methode. Deze methode is identiek aan de digitale handtekening van de HTML-gateway en de push-response. De uitleg van de digitale handtekening vindt u bij digitale handtekening

URLs

De NVP productie gateway:
https://checkout.buckaroo.nl/nvp/

Voor testdoeleinden is er een aparte NVP gateway gemaakt. Deze test gateway vindt u op de volgende locatie:

https://testcheckout.buckaroo.nl/nvp/
Elke verzoek naar deze test gateway zal resulteren in een transactie.

Service Operations

De NVP gateway ondersteunt 2 operations:

  1. TransactionRequest: Gebruik deze operation om een transactie uit te voeren door de payment engine (zoals het doen van een transactie of het uitvoeren van een refund). Dit is de standaard operation en kan weggelaten worden.
  2. TransactionStatus: Dit request geeft informatie over de status van de transactie. Het formaat van het resultaat is gelijk aan die van de push-response.

Wanneer er een niet standaard operatie aangesproken moet worden moet de naam van de operation aan de url worden toegevoegd in het volgende formaat:

<gateway_url>?op=<operation_name>. 

Bijvoorbeeld: ~https//checkout.buckaroo.nl/nvp/?op=transactionstatus

TransactionRequest

Dit verzoek kan gebruikt worden om een transactie te doen via de payment engine. Deze transactie kan een payment(betaling), een refund of een authorisatie zijn. In het kort het kan dus elk verzoek zijn dat eindigt in een transactie. Het verzoek is zeer algemeen in de structuur. Het is een syntax waarin elk payment engine verzoek kan worden gegoten om naar de NVP gateway te communiceren. Voor een verklaring wat er voor elke service en actie nodig is zie daarvoor de desbetreffende services omschrijving.

Element Omschrijving Verplicht bij actie
brq_payment_method De servicecode van de gewenste betaalmethode. Bijv: ideal Pay, Authorize
brq_websitekey De unieke key van de website waarvoor de betaling verricht wordt. Verplicht bij alle acties
brq_culture ISO-culturecode die de taal en het land van de consument aangeeft. Bijv.: nl-NL, en-US, de-DE. Op basis van de taal wordt meertaligheid toegepast. Ondersteunde talen: NL, EN, DE. -
brq_signature De digitale handtekening. Voor de berekening hiervan zie Digitale handtekening. Verplicht bij alle acties
brq_currency De valutacode (bijv. EUR, USD, GBP). Let op dat de opgegeven valuta
ondersteund wordt door de opgegeven betaalmethode.
Verplicht bij alle acties
brq_amount Het te betalen bedrag, formaat: 12.34 (gebruik altijd een punt als decimaalscheidingsteken). Wanneer "1" wordt ingestuurd wordt dit gezien als "1.00".
Let op: Een transactie moet brq_amount of brq_amount_credit bevatten. Het is niet toegestaan beide tegelijkertijd in te sturen.
Verplicht bij alle acties
brq_amount_credit Het creditbedrag, formaat: 12.34 (gebruik altijd een punt als decimaalscheidingsteken). Wanneer "1" wordt ingestuurd wordt dit gezien als "1.00".
Let op: Een transactie moet brq_amount of brq_amount_credit bevatten. Het is niet toegestaan beide tegelijkertijd in te sturen.
Verplicht bij alle acties
brq_invoicenumber Het unieke factuurnummer dat vermeld wordt bij de betaling.
Dit is een vrij tekstveld van maximaal 255 tekens.
Pay, PayRecurrent
brq_ordernumber Het ordernummer van de transactie, dit mag een combinatie zijn van alfanummerieke karakters zijn.
-
brq_description De omschrijving van de transactie. -
brq_clientip Het ip adres van de klant of medewerker voor wie de transactie wordt uitgevoerd.
-
brq_channel Het kanaal waarover de transactie wordt uitgevoerd. Op dit moment is het standaard web. Hiermee wordt aangegeven dat het om een transactie gaat die via een website/webapp wordt afgehandeld.
-
brq_return De return URL waarnaar de consument na betaling wordt toegestuurd. *
brq_returncancel De return URL als de consument de betaling annuleert. *
brq_returnerror De return URL als een fout optreedt tijdens het betaalproces. *
brq_returnreject De return URL als de betaling door een externe processor wordt afgewezen. *
brq_originaltransaction De transactie key van de originele transactie
Refund,
PayRecurrent,
Capture,
CancelAuthorize
brq_startrecurrent Sommige services ondersteunen recurring payments (zie hiervoor de of de services de actie PayRecurrent ondersteunen). Voordat er een recurrent payment (vervolgbetaling van reeks) plaats kan vinden moet er een normale transactie (eerste betaling van reeks) hebben plaatsgevonden waarbij dit veld met true is ingezonden (standaard waarde is false). -
(elementen) beginnend met brq_service_ [servicecode]_ Aanvullende parameters voor de betaalmethode en/of aanvullende diensten. Kijk voor meer informatie: specificatie per service.
brq_service_ [servicecode]_action De uit te voeren actie voor de opgegeven service. Bijv.: om voor iDEAL de actie Pay op te geven:
Brq_service_ideal_action=Pay
Ja, wanneer de service is gespecificeerd
brq_additional_ service Servicecode voor een aanvullende dienst. Bijv: creditmanagement.
Dit veld kan meerdere keren worden opgegeven.
-
brq_continue_on_incomplete Wanneer er een fout ontstaat met betrekking tot missende of incorrecte invoer en de invoer kan door de consument worden opgegeven is het mogelijk om met behulp van dit veld de transactie door te laten gaan in plaats van dat de transactie mislukt. Door het veld te vullen met de waarde 'RedirectToHTML' wordt er een redirect URL naar de HTML gateway terug gegeven. Hierop kan de klant de missende of incorrecte informatie opgeven.

Voorbeeld. Er wordt een verzoek ingestuurd voor iDEAL zonder de issuer, zonder het veld brq_continue_on_incomplete of gevuld met 'no' zal de transactie mislukken. Wanneer gevuld met de waarde 'RedirectToHTML' wordt er een redirect URL terug gegeven waarop de klant alsnog de bank keuze kan doen.

Mogelijke waardes zijn: No en RedirectToHTML

brq_requestedservices een komma gescheiden lijst van services waaruit de klant de betaalmethode kan kiezen wanneer deze naar de HTML gateway wordt doorgestuurd.

Wanneer 'continue_in_incomplete' is meegestuurd met de waarde 'RedirectToHTML' en er is geen betaalmethode opgegeven wordt de klant naar doorgesturd naar een betaalmethode selectie scherm. Dit scherm toont standaard alle afgenomen betaalmethodes, Wanneer een aangepaste lijst getoond moet worden moet dat in dit veld worden opgegeven.

Bijv.: ideal,visa,mastercard,paypal

Naast de waardes die beginnen met brq_ worden ook additionele en custom variabelen ondersteund. Deze moeten beginnen met add_ of cust_. Andere velden worden genegeerd en worden ook niet teruggestuurd in de response.

Voorbeeld

brq_websitekey = XyZ123AbC
brq_amount = 0.01
brq_currency = EUR
brq_invoicenumber = INV12345678
brq_description = Test payment
brq_culture = nl-NL
brq_return = http://yourwebshop.tld/returnpage.php
brq_returncancel = http://yourwebshop.tld/returnpage_cancel.php
brq_returnerror http://yourwebshop.tld/returnpage_error.php
brq_returnreject = http://yourwebshop.tld/returnpage_reject.php
brq_signature = bb5668ec1b3755c6bae401076877f8a183e36852
brq_service_paypal_action = Pay
brq_payment_method = paypal


Service Velden

Als een service optionele of verplichte extra request parameters heeft moeten deze worden mee gestuurd in het formaat Brq_service_[servicecode]_[parametername] (bijv. brq_service_ideal_issuer). Wanneer er optionele velden zijn die ook door de klant ingevuld kunnen worden maar niet meegestuurd worden worden deze niet door de gateway alsnog gevraagd (dit in tegenstelling tot de HTML gateway die de klant de optie geeft deze alsnog in te vullen). Wanneer verplichte velden alleen door de klant mogen worden ingevuld zal er een redirecturl terug gegeven worden waar de klant naar toe gestuurd moet worden. Hier wordt de klant om de benodigde gegevens gevraagd. Dit scenario zal het meeste waarschijnlijk bij een creditcard betaling voorkomen. Dit omdat u als merchant geen creditcardgegevens mag opgeven, tenzij u PCI-gecertificeerd bent.

Als er meer dan 1 service wordt opgegeven kan de additionele service alleen een aanvullende actie specificeren. Ook kan het nuttig zijn zodra er meer dan 1 service gebruikt wordt om gebruik te maken van globale velden. Deze kunnen dan gebruikt worden door meerdere services. Op deze manier hoeven gegevens niet meerdere keren te worden opgegeven en het verzekerd dat de zelfde gegevens door alle services gebruikt worden. Een global veld heeft het formaat brq_[parametername] (bijv. Brq_customerfirstname).

Het is mogelijk om naast de Buckaroo variabelen ook merchant eigen variabelen mee te sturen met elk betaalverzoek. Deze extra variabelen worden ook in de response en push updates meegegeven. Er zijn 2 types van deze variabelen:


Custom variabelen: deze worden voorgeconfigureerd in de Payment Plaza. Voordeel hiervan is dat deze zichtbaar en doorzoekbaar zijn in de Payment Plaza. Dit omdat de waarden worden opgeslagen in de Payment Plaza. Ook kan het type van het veld worden opgegeven. Daarmee ontstaat de mogelijkheid van het controleren op formaat. Het formaat is gedefinieerd als cust_[variablename] (bijv. cust_event).

Additional variabelen: deze worden niet voorgeconfigureerd. De additional variabelen zijn ook in de Payment Plaza te zien in de transactie details, maar hier kan niet op worden gezocht. Het formaat is gedefineieerd als add_[variablename] (bijv. add_myshopreference).

Opmerking:

  1. het indienen van de transactie;
  2. afhandeling van het betaalverzoek;
  3. redirect nadat de consument de betaalpoging heeft afgemaakt;
  4. push van de resultaten van de betaalpoging;
  5. het opvragen van een transactie rapportage.


Customer en additional velden.jpg

Trefwoorden: add; cust; additional; custom; variabelen; additionele; additioneel

response

Wanneer het verzoek een correcte structuur en correcte signature heeft zal een transactie aangemaakt worden in de Payment Engine en een response zal geretourneerd worden die er als volgt uit ziet.

Element Omschrijving Optioneel
brq_apiresult Het resultaat van de aanroep van de gateway. Kan een van de waardes zijn genoemd in het hoofdstuk "NVP gebruik".
brq_payment De key van de Payment. Deze waarde wordt alleen terug gestuurd als de transactie tot een daadwerkelijke betaling heeft geleid. Ja
brq_payment_method De servicecode van de methode waarmee de betaling is uitgevoerd. Ja
brq_statuscode De statuscode van de transactie
brq_statuscode_detail Een detail status code welke een extra uitleg geeft aan de huidige status code. Ja
brq_statusmessage Een bericht over de status code
brq_invoicenumber Het invoicenummer dat in het verzoek is opgegeven
brq_amount_credit Het creditbedrag dat in het verzoek is opgegeven, als het is opgegeven. Ja
brq_amount Het bedrag dat in het verzoek is opgegeven, als het is opgegeven. Ja
brq_currency De valuta van de transactie (bijv. EUR, USD, GBP).
brq_test Als de transactie verwerkt is in de test mode is deze waarde 'true', in live modus is deze 'false'.
brq_timestamp De tijd waarop de betaling zijn huidige status heeft ontvangen.
brq_service_[servicecode]_[parametername] Output parameters voor de gevraagde services. Zie hiervoor de service handleiding voor een lijst van parameters.
cust_[parametername] De voorgedefiniëerde custom variabelen welke zijn meegestuurd met het originele verzoek.
add_[parametername] De additionele variabelen welke zijn meegestuurd met het originele verzoek.
brq_transactions Een of meer transactie keys. Een key als er een onderliggende transactie is aangemaakt voor de betaling. Meerdere als er meerdere onderliggende transacties zijn aangemaakt voor de betaling.
brq_transaction_method De service waarmee de transactie is uitgevoerd (alleen een transactie is verwerkt). Ja
brq_transaction_type De transactie type code van de transactie (alleen een transactie is verwerkt). Ja
brq_actionrequired De actie die de merchant moet uitvoeren om de transactie verder te verwerken. kan zijn: 'redirect'. Ja
brq_redirecturl Als er een een 'brq_actionrequired' is terug gestuurd en de actie is 'redirect', wordt er in dit veld de redirecturl opgegeven waar de klant naar toegestuurd moet worden. Dit kan voorkomen als er extra invoer vereist wordt bij Buckaroo of een acquirer (bijv. 3D secure, iDEAL bank login, e.d.) Ja

Response, Custom en Additionele parameters

Een verzoek kan extra informatie informatie terug geven in sommige gevallen. Het is mogelijk dat een bepaalde service extra gegevens terug stuurt na het uitvoeren van het verzoek, deze informatie wordt dan ook terug gestuurd in de response parameters voor de service.

Retour pagina's en Pushes

In sommige gevallen moet de klant worden doorgestuurd naar een webpagina om het transactieproces af te ronden. In deze gevallen wordt een redirecturl meegegeven in de response van het transactie verzoek. Wanneer de klant afrond op die pagina zal hij worden terug gestuurd naar een voor ingestelde pagina op de website van de merchant. Wanneer de klant naar de die pagina wordt terug gestuurd zal de transactie gegevens worden meegestuurd met de klant.
Voor sommige transacties kan het zijn dat de daadwerkelijke afronding van de betaling later plaats vind. Bijvoorbeeld voor een bankoverboeking, deze kost altijd een aantal werkdagen om af te ronden. Wanneer de push functionaliteit is ingeschakeld via de payment plaza wordt elke status wijziging op een transactie en/of payment gepushed wanneer deze plaats vind. The push roept een webpagina aan op de website van de merchant en zend de transactie status naar deze webpagina, op dezelfde manier als bij de return pagina. Let op dat de push altijd plaats vind op een transactie.

Post en Push data

Element Omschrijving optioneel
brq_payment De key van de Payment. Deze waarde wordt alleen terug gestuurd als de transactie tot een daadwerkelijke betaling heeft geleid. Ja
brq_payment_method De servicecode van de methode waarmee de betaling is uitgevoerd.
brq_statuscode De statuscode van de transactie Nee
brq_statuscode_detail Een detail status code welke een extra uitleg geeft over de huidige status code. Ja
brq_statusmessage Een bericht over de status code Ja
brq_invoicenumber Het invoicenummer dat in het verzoek is opgegeven Nee
brq_amount_credit Het creditbedrag dat in het verzoek is opgegeven, als het is opgegeven. Ja
brq_amount Het bedrag dat in het verzoek is opgegeven, als het is opgegeven. Ja
brq_currency De valuta van de transactie (bijv. EUR, USD, GBP). Nee
brq_timestamp De tijd waarop de betaling zijn huidige status heeft ontvangen. Nee
brq_service_[servicecode]_[parametername] Output parameters voor de gevraagde services. Zie hiervoor de service handleiding voor een lijst van parameters. Ja
cust_[parametername] De voorgedefiniëerde custom variabelen welke zijn meegestuurd met het originele verzoek. Ja
add_[parametername] De additionele variabelen welke zijn meegestuurd met het originele verzoek. ja
brq_transactions Een of meer transactie keys. Een key als er een onderliggende transactie is aangemaakt voor de betaling. Meerdere als er meerdere onderliggende transacties zijn die gelinkt zijn aan de betaling. Nee
brq_transaction_method De service waarmee de transactie is uitgevoerd (alleen wanneer een transactie is verwerkt). Nee
brq_transaction_type De transactie type code van de transactie (alleen wanneer een transactie is verwerkt). Nee
brq_mutationtype Het mutatie type van de transactie, dit kan 'collecting','processing','informational' of 'notset' zijn. Ja
brq_signature De digitale handtekening. Voor de berekening hiervan zie Digitale handtekening SSL/HTML. Nee

Om te zorgen dat we de afzender van de transactie kunnen verifiëren en zeker te zijn dat het bericht onderweg niet aangepast is, maakt Buckaroo gebruik van een digitale handtekening bij elke transactie.

Deze handtekening bestaat uit een hash van alle velden uit het bericht, aangevuld met een secret key.
De secret key is instelbaar op de Payment Plaza onder Profiel > Beveiliging.

De berekening

De berekening van de handtekening werkt als volgt:

  1. Maak een lijst met alle velden in het payment request beginnend met brq_, add_ of cust_, behalve brq_signature, in het volgende formaat:
    brq_veldnaam=Waarde
  2. Sorteer deze velden op alfabetische volgorde op basis van de veldnaam (brq_amount komt vóór brq_websitekey).
    Let op: sortering moet niet-hoofdlettergevoelig gebeuren (brq_active komt vóór BRQ_AMOUNT). Hoofdletters in de veldnamen moeten wel behouden blijven.
    Bijvoorbeeld: BRQ_AMOUNT=1.00brq_currency=EURbrq_websitekey=asdfasdfsecret
  3. Voeg al deze waardes samen, geformateerd zoals genoemd in punt 1, in een string. Gebruik geen scheidingstekens of witruimtes.
    Bijvoorbeeld: BRQ_AMOUNT=1.00brq_currency=EURbrq_websitekey=asdfasdfsecretkey
  4. Voeg hier de pre-shared secret-key toe aan het eind van deze string.
  5. Bereken van deze string een hash met het SHA-1 algoritme. Voer de hash uit in hexadecimaal formaat.

Let op Bij de return en de push moeten de gegevens volledig ge-decode zijn, voordat de signature kan worden berekend.

Het gebruik van het SHA1-encryptiealgoritme verschilt per ontwikkelplatform. De meeste talen (zoals PHP en ASP.NET) hebben standaardimplementaties van het SHA1-algoritme. Voor andere talen als classic ASP kunt u op internet implementaties van het SHA1-algoritme vinden.

SHA-1 voorbeelden

PHP

<source lang="php">$signature3 = sha1($requestFields);</source>

C#/.NET

<source lang="csharp">

using System.Text; using System.Security.Cryptography;

string message = "string that needs to be hashed";

SHA1CryptoServiceProvider sha1Provider = new SHA1CryptoServiceProvider();

//convert input to byte array byte[] messageArray = Encoding.UTF8.GetBytes(message);

//calculate hash over byte array byte[] hash1 = sha1Provider.ComputeHash(messageArray);

//convert byte array to string by printing each hex value. foreach (byte b in hash1) {

   builder.Append(b.ToString("x2"));

} //get the result from the string builder object. String Result = builder.ToString(); <source></source>

Testen

Wanneer er gestart wordt met de implementatie van de gateway adviseren wij om eerst gebruik te maken van de test gateway. Alle transacties en payments die worden aangemaakt door een verzoek naar de test gateway te sturen zijn test transacties. Dit betekend dat waar mogelijk een sandbox omgeving van een derde partij wordt gebruikt. In andere gevallen zal de transactie direct op geslaagd komen te staan.