TargetPay

Documentatie: Overboekingen

1. Algemeen
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. Opvragen van een betaalkenmerk
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
rtloLayoutcodeNumeriekJa
descriptionOmschrijvingAlfanumeriekJa
amountBedrag in eurocentenAlfanumeriekJa
useripVermeld het IP adres van de klantAlfanumeriekJa
reporturlRapporteer naar URLAlfanumeriekJa
saltEen willekeurige reeks karakters voor berekenen van checksum van de reporturl (zie: reporturl). Maximaal 32 tekens.AlfanumeriekJa
emailE-mailadres van uw klantAlfanumeriekNee
returnurlReturn URLAlfanumeriekNee
customer_cnameNaam consument. Maximaal 34 tekens.Alfanumeriek plus punten en spatiesNee
customer_cbankRekeningnummer consument.Alfanumeriek plus puntenNee
customer_invoiceFactuur kenmerk. Maximaal 25 tekens.Alfanumeriek plus punten, strepen, spaties en underscoresNee

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. Status opvragen
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
rtloLayoutcodeNumeriekJa
trxidBetaalkenmerkNumeriekJa
checksumChecksumAlfanumeriekJa
once'Reeds ingewisseld' melding?0 of 1Ja

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;
}
?>