In dit document staat beschreven hoe u met TargetPay uw klanten kunt laten betalen via een bankoverboeking.
Bankoverboekingen werken vanuit elke bank ter wereld en zijn daarom de perfecte aanvulling op producten als iDEAL (Nederland), Mister Cash (België), etc.
1.1 Werking van bankoverschrijving in een notedop
Met de API (technische koppeling) voor bankoverboekingen genereert u een betaalkenmerk en geeft u aan wat wij moeten doen zodra er een betaling is binnengekomen
met dit betaalkenmerk.
Als u van ons een betaalkenmerk heeft gekregen vraagt u uw klant om geld over te maken naar de Stichting Derdengelden Digiwallet onder vermelding van het betaalkenmerk.
Hier staat uw geld veilig tot aan de wekelijkse uitbetaling van het totale saldo.
Zodra ons systeem ziet dat de betaling binnengekomen is krijgt u een terugkoppeling. Wij roepen een URL aan op uw server met daarin wederom het betaalkenmerk, hoeveel er betaald is
(mocht dit bijv. een paar cent meer zijn). Als u het e-mailadres weet van uw klant en u geeft dit door aan de API dan zal er een mail gestuurd worden naar uw klant
met daarin uw 'return url' ofwel een link terug uw website of webwinkel in voor verdere stappen.
2.1 Aanroep
U vraagt allereerst een betaalkenmerk op met een HTTP GET of POST naar:
https://www.targetpay.com/bankwire/start
Met de volgende parameters:
Variabele |
Naam |
Formaat |
Verplicht |
rtlo | Layoutcode | Numeriek | Ja |
description | Omschrijving | Alfanumeriek | Ja |
amount | Bedrag in eurocenten | Alfanumeriek | Ja |
userip | Vermeld het IP adres van de klant | Alfanumeriek | Ja |
reporturl | Rapporteer naar URL | Alfanumeriek | Ja |
salt | Een willekeurige reeks karakters voor berekenen van checksum van de reporturl (zie: reporturl). Maximaal 32 tekens. | Alfanumeriek | Ja |
email | E-mailadres van uw klant | Alfanumeriek | Nee |
returnurl | Return URL | Alfanumeriek | Nee |
customer_cname | Naam consument. Maximaal 34 tekens. | Alfanumeriek plus punten en spaties | Nee |
customer_cbank | Rekeningnummer consument. | Alfanumeriek plus punten | Nee |
customer_invoice | Factuur kenmerk. Maximaal 25 tekens. | Alfanumeriek plus punten, strepen, spaties en underscores | Nee |
Toelichting per variabele:
- rtlo
De layoutcode waarop de betaling geboekt moet worden. Zie subaccounts.
- description
Duidelijke omschrijving van de te leveren dienst. Alleen letters of cijfers, maximaal 32 tekens.
- userip
Vermeld het IP adres of een ander uniek ID van de klant. Bijv. een klantnummer.
- amount
Het in rekening te brengen bedrag in eurocenten. Mogelijke waarden: minimaal 84, maximaal 1000000 (€ 0,84 - € 10.000)
- reporturl
Deze URL wordt aangeroepen zodra de betaling bij ons is binnen gekomen.
Aan deze URL voegen we 5 parameters toe:
- trxid: het betaalkenmerk
- rtlo: layoutcode
- amountdue: het bedrag dat betaald had moeten worden
- amountpaid: het daadwerkelijk betaalde bedrag in eurocenten
- checksum: controlegetal waarmee u kunt controleren of de terugmelding van ons systeem afkomstig is. Checksum wordt als volgt berekend, het is de MD5 van (achter elkaar gezet): trxid, rtlo, amount en salt (zie hierboven). Voorbeeld: stel dat u voor 'salt' doorgaf 'e381277' dan kunt u in PHP de juiste checksum uitrekenen met:
$checksum = md5($_REQUEST["trxid"].$_REQUEST["rtlo"].$_REQUEST["amountdue"].$_REQUEST["amountpaid"]."e381277");
De report URL wordt OOK aangeroepen als er te weinig betaald wordt. U dient dus te controleren of het juiste bedrag betaald is!
De reporturl wordt middels een HTTP GET request aangeroepen vanaf de Targetpay server.
Voorbeeld van een terugmelding kan zijn:
http://www.test.nl/reporturl?trxid=28374766&rtlo=39981&amountdue=1000&amountpaid=1195& checksum=0782efd61b7a6b02e602cc6a11673ec9
Let op: verwar de reporturl niet met de returnurl. Uw bezoeker krijgt de reporturl nooit te zien, dit gebeurt 'onder water'.
- email
Vul hier het e-mailadres van uw klant in als dit bekend is en als u wilt dat wij uw klant een mail sturen zodra de betaling binnen is gekomen. Wij verwijzen uw klant in dat geval naar de opgegeven return URL, mits die vermeld is.
- returnurl
Als u een e-mailadres opgegeven heeft zal de return URL gemaild worden na betaling. Achter de return URL plakken wij als parameter trxid met daarin het betaalkenmerk zodat u weet om welke betaling het gaat.
- customer_cname
Naam consument.(voor betere transactie identificatie)
- customer_cbank
Rekeningnummer consument.(voor betere transactie identificatie)
- customer_invoice
Factuur kenmerk.(voor betere transactie identificatie)
2.2 Resultaatcode's
Als de overboeking met succes klaargezet is, ontvangt u een resultaat in de vorm:
000000 aaaa|bbbb|cccc|dddd|eeee|ffff
- aaaa : Het XXXX-XX-YY-ZZZZ betaalkenmerk voor uw klant om te vermelden in de omschrijving;
- bbbb : Rekeningnummer waarnaar uw klant het geld overmaakt;
- cccc : IBAN code van het rekeningnummer (voor buitenlandse betalingen);
- dddd : BIC code van het rekening nummer (voor buitenlandse betalingen);
- eeee : De exacte tenaamgestelde van deze bankrekening, om misverstanden te voorkomen.
- ffff : Naam van onze bank
Voorbeeld:
000000 XXXX-XX-YY-ZZZZ|5940.74.231|NL44ABNA0594074231|ABNANL2A|Stichting Derdengelden Digiwallet|Rabobank
Beschrijving betaalkemerk:
XXXX-XX : Uw layoutcode eventueel vooraf gegaan door een 0
YY: letter combinatie beginnend met AA. Deze wordt veranderd zodra het ZZZZ (volgnummer) al eerder is voorgekomen op uw layoutcode
ZZZZ volgnummer
Als er een fout is opgetreden, dan wordt een van de volgende foutcodes geretourneerd:
TP0001 No layoutcode specified
TP0002 Amount too low
TP0003 Amount too high
TP0004 Invalid return URL
TP0005 Invalid or no report URL
TP0006 No description specified
TP0007 Invalid e-mailaddress
TP0009 Invalid or no user IP given
TP0010 No value for salt specified
TP0011 Value for salt is too long
TP0012 Invalid customer cname
TP0013 invalid customer cbank
TP0014 invalid customer invoice
TP0999 Layoutcode expected, customer number given. Please use your correct layoutcode.
2.3 Call to action
Nu u deze gegevens hebt is het heel belangrijk duidelijk te communiceren wat van de klant verwacht wordt.
Gebruikt u bijvoorbeeld dit template:
Bedankt voor uw bestelling in onze webwinkel!
U ontvangt de door u bestelde producten zodra we uw betaling per bank ontvangen hebben.
U ontvangt een mail ter bevestiging op ".
klant@klantsite.nl zodra uw betaling ontvangen is.
U kunt het factuurbedrag van € 12,34 overmaken op bankrekening
NL44ABNA0594074231 ten name van Stichting Derdengelden Digiwallet*
Vermeld u altijd het betaalkenmerk 0628-65-AA-1234 in de omschrijving, anders kan
uw betaling niet verwerkt worden.
Betaalt u niet vanuit Nederland?
Gebruikt u dan s.v.p. de volgende gegevens voor de betaling:
IBAN: | NL44ABNA0594074231 |
BIC/Swift: | ABNANL2A |
Bank-naam: | ABNAMRO-bank |
Let er alstublieft op dat u ervoor kiest dat de kosten in het buitenland voor u zijn (optie: OUR) |
* De betalingen voor onze webwinkel worden verwerkt door TargetMedia.
TargetMedia is gecertificeerd als Collecting Payment Service Provider door Currence. Dat houdt in dat zij aan strenge
eisen dient te voldoen als het gaat om de veiligheid van de betalingen voor zowel u als ons als webwinkelier.
|
U kunt bovenstaand template uiteraard geheel naar wens aanpassen, maar vermeld s.v.p. altijd duidelijk dat het betaalkenmerk in de omschrijving opgenomen moet worden.
Zonder betaalkenmerk is het niet mogelijk de betaling aan uw account te koppelen.
3.1 Aanroep
Als u wilt kunt u ook actief de status van een betaling bij ons navragen. Dat kan met een aanroep naar:
https://www.targetpay.com/bankwire/check
Met de volgende parameters:
Variabele |
Naam |
Formaat |
Verplicht |
rtlo | Layoutcode | Numeriek | Ja |
trxid | Betaalkenmerk | Numeriek | Ja |
checksum | Checksum | Alfanumeriek | Ja |
once | 'Reeds ingewisseld' melding? | 0 of 1 | Ja |
Toelichting per variabele:
- rtlo
Layoutcode (zelfde waarde als meegegeven onder 5.1)
- trxid
Transactie ID, geretourneerd in de vorige stap (16 tekens)
- checksum
De checksum is nodig om zeker te weten dat het verzoek van u afkomt. De checksum wordt berekend middels: $checksum = md5($trxid.$rtlo.'salt'); Zie ook het kopje reporturl hierboven. Let wel, 'amount' maakt in dit geval geen onderdeel uit van de checksum berekening.
- once
Als u voor once '1' invult dan zal slechts 1x een OK status teruggegeven worden.
Als de bovenstaande URL nog een keer wordt aangeroepen voor hetzelfde Transactie ID dan krijgt u een foutmelding
TP00014 (Reeds ingewisseld) terug.
Als u voor once '0' invult dan zal steeds een OK status terug blijven komen.
Vul bij twijfel 1 in, zo weet u zeker dat een dienst niet meerdere malen geleverd wordt als de bezoeker op
Refresh/F5 zou drukken.
3.2 Resultaatcode's
Als er een betaling ontvangen is, ontvangt u als antwoord:
000000 OK|verschuldigd bedrag|daadwerkelijk betaald bedrag
dus bijvoorbeeld als er € 7,95 betaald is, terwijl er eigenlijk € 7,50 betaald had moeten worden:
000000 OK|750|795
U dient zelf te controleren of het ontvangen bedrag juist is! Het is niet mogelijk om op hetzelfde transactienummer een 2e deel betaling te doen.
Mogelijke foutcodes zijn:
TP0010 Transaction not finished, try again later
TP0014 Already redeemed at XXXX-XX-XX XX:XX:XX
TP0020 No layoutcode given
TP0021 No transaction ID given
TP0022 No transaction with this ID
TP0023 Layoutcode doesn't match transaction
TP0024 Checksum incorrect..
<?php
$rtlo=xxxxx;
$description="Bankwire Example";
$amount=90;
$returnurl="http://www.uwsite.nl/BankwireExample.php";
$reporturl="http://www.uwsite.nl/BankwireExample.php";
$salt="--secretrandomstring--";
$customer_email = "uwklant@eendomein.nl";
// Customer returns on the returnurl, now we check the transaction status
if( isset($_GET['trxid']) && isset($_GET['rtlo']) ){
// 000000 OK means Status is successful or partial.
if(substr(($status=CheckReturnurl($_GET['rtlo'],$_GET['trxid'],$salt )),0,9) == "000000 OK" ){
$aResponse = explode('|', $status );
if($aResponse[1]!=$aResponse[2]) {
// Update your orderinfo to partial payment
die( "Status is Partial ...<br>We received € ".
number_format($aResponse[2]/100,2,",",".").
"<br>in stead of € ". number_format($aResponse[1]/100,2,",",".").".");
}
else {
echo
// Update your orderinfo to Successful full payment
die( "Status was successful. We expected and received € ".
number_format($aResponse[2]/100,2,",",".")."" );
}
}
//In all other cases do not delever(yet)
// Update orderstatus to failed
else die( $status );
}
// As soon as the payment has been received, the targetpay server calls your reporturl
if ( isset($_REQUEST['trxid']) && isset($_REQUEST['rtlo']) && isset($_REQUEST['amountdue']) &&
isset($_REQUEST['amountpaid'])&& isset($_REQUEST['checksum'])){
HandleReporturl( $_REQUEST['trxid'], $_REQUEST['rtlo'], $_REQUEST['amountdue'], $_REQUEST['amountpaid'],
$salt, $_REQUEST['checksum']);
}
// Show payment screen to customer
StartTransaction( $rtlo, $description, $amount, $returnurl, $reporturl, $salt, $customer_email);
die();
// Request Targetpay for a transaction ID and show it to your customer
function StartTransaction( $rtlo, $description, $amount, $returnurl, $reporturl, $salt, $mail ){
$url= "https://www.targetpay.com/bankwire/start?".
"rtlo=".$rtlo.
"&description=".urlencode(substr($description,0,32)).
"&amount=".$amount.
"&userip=".urlencode($_SERVER['REMOTE_ADDR']).
"&reporturl=".urlencode($reporturl).
"&salt=".urlencode($salt).
"&email=".urlencode($mail).
"&returnurl=".urlencode($returnurl);
$strResponse = httpGetRequest($url);
$aResponse = explode('|', $strResponse );
# Bad response
if ( !isset ( $aResponse[1] ) ) die('Error' . $aResponse[0] );
$responsetype = explode ( ' ', $aResponse[0] );
$trxid = $responsetype[1];
if( $responsetype[0] == "000000" ){
echo "<table WIDTH=\"700\" border=\"1\" BGCOLOR=\"Aqua\"><tr><td>".
"Bedankt voor uw bestelling in onze webwinkel!<br><br>".
"U ontvangt de door u bestelde producten ".
"zodra we uw betaling per bank ontvangen hebben.<br>";
if($mail <> "" )
echo "Zodra uw betaling is ontvangen, ".
" ontvangt u een mail ter bevestiging op het E-mail adres ".
$mail. " <br><br>";
echo "U kunt het factuurbedrag van € ". number_format($amount/100,2,",",".") .
" overmaken op bankrekening <b>".
$aResponse[2]."</b> ten name van <b>".$aResponse[4]."*</b><br>".
"Vermeldt u altijd het betaalkenmerk <b>".$trxid.
"</b> in de omschrijving, anders kan uw betaling niet verwerkt worden.".
"<br><br>".
"Betaalt u niet vanuit Nederland?<br>".
"Gebruikt u dan s.v.p. de volgende gegevens voor de betaling:<br><br>".
"IBAN: ".$aResponse[2].
"<br>BIC/SWIFT: ".$aResponse[3].
"<br>Banknaam: ".$aResponse[5].
"<br>".
"Let er alstublieft op dat u ervoor kiest dat de kosten in het buitenland voor u zijn".
" (optie: OUR)<br><br>".
"<i>*De betalingen voor onze webwinkel worden verwerkt door TargetMedia. ".
"TargetMedia is gecertificeerd als Collecting Payment Service Provider door Currence.".
"Dat houdt in dat zij aan strenge eisen dient te voldoen".
" als het gaat om veiligheid voor de betalingen".
"van zowel u als ons als webwinkelier.</i>".
"</td></tr></table>";
return $aResponse[1];
}
else die($aResponse[0]);
}
// Controleer de status van de betaling.
// Deze URL wordt door de consument aangeroepen
function CheckReturnurl($rtlo, $trxid, $salt){
$once=1;
$test=1; // Set to 1 for testing
$url= "https://www.targetpay.com/bankwire/check?".
"rtlo=".$rtlo.
"&trxid=".$trxid.
"&checksum=".md5( $trxid.$rtlo.$salt ).
"&once=".$once.
"&test=".$test;
return httpGetRequest($url);
}
// Handler voor the reporturl.
// Deze wordt vanaf de TargetPay server aangeroepen.
function HandleReporturl($trxid, $rtlo, $amountdue, $amountpayed, $salt, $cs ){
if( substr($_SERVER['REMOTE_ADDR'],0,10) == "89.184.168" ||
substr($_SERVER['REMOTE_ADDR'],0,9) == "78.152.58"
){
$checksum=md5($trxid.$rtlo.$amountdue.$amountpayed.$salt );
if( $cs==$checksum ){
// Update your orderinfo status here.
//reporturl should return OK to TargetPay.
die( "OK" );
}
else{
die( "CHECKSUM FAILLURE");
}
}else{
die("IP address not correct... This call is not from TargetPay");
}
}
function httpGetRequest($url){
$ch = curl_init( $url );
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1) ;
$strResponse = curl_exec($ch);
curl_close($ch);
if ( $strResponse === false )
die("Could not fetch response " . $url );
return $strResponse;
}
?>
|