Met de Qantani API kunt u betalingen uitvoeren met alle beschikbare betaalmethoden en de status van een betaling controleren.

1. Verbinden met de API

Gebruik de volgende url om te verbinden met de API:
https://www.qantanipayments.com/api/
Deze url gaat via HTTPS en gebruikt SSL. Verbinden via HTTP is niet mogelijk.

1.1 Data versturen

Elke request bestaat uit 1 XML file die gepost moet worden in de data variabel. Elke XML file moet UTF-8 gecodeerd zijn. Let vooral op karakters als < en &. Deze moeten respectievelijk worden gecodeerd als &lt; en &amp;.

1.2 XML berichten

Elk XML bericht bestaat uit de volgende drie onderdelen:
  • Actie
    • de functie die wordt aangeroepen.
    • het versienummer van de API. De huidige versie is 1.
  • Merchant
    • de ID van de merchant
    • de key van de merchant
    • de checksum parameter
  • Parameters (optioneel)
    • deze parameters zijn afhankelijk van de functie die u aanroept.

1.3 Checksum genereren


De checksum string wordt als volgt opgebouwd:
  1. De lijst met parameters die u verstuurt is bijvoorbeeld:
  2. {
    ‘Amount’: ‘[Bedrag]’,
    ‘Currency’: ‘[Valuta]’,
    ‘Bank’:‘[Bank code]’,
    ‘Description’:‘[Omschrijving van de transactie]’,
    ‘Return’:‘[Return URL]’
    }
    
    We nemen de volgende voorbeeld gegevens: Amount is 9.95, Bank is ABN_AMRO, Currency is EUR, Description is Testbetaling, Return is http://www.mijnwebsite.nl/bedankt.php en de merchant secret is 12345.
  3. Sorteer de parameters op alfabetische volgorde:
  4. {
    ‘Amount’: 9.95,
    ‘Bank’:‘ABN_AMRO’,
    ‘Currency’: ‘EUR’,
    ‘Description’:‘Testbetaling’,
    ‘Return’:‘http://www.mijnwebsite.nl/bedankt.php’
    }
    
  5. Voeg alle parameters toe aan een string:
  6. ‘9.95ABN_AMROEURTestbetalinghttp://www.mijnwebsite.nl/bedankt.php’
    
  7. Voeg de merchant secret toe aan het einde van de string:
  8. ‘9.95ABN_AMROEURTestbetalinghttp://www.mijnwebsite.nl/bedankt.php12345’
    
  9. Zet de string om in een SHA1-string:
  10. ‘434c7a1599118ef14d0f2aa1811c7a48a1a5371b’
    
    Dit is de checksum! Let op! De checksum voor PayPal en Achteraf betalen transacties worden op een andere wijze berekend (zie paragraaf 4.3).
Zet alleen de merchant secret om in een SHA1-string wanneer er geen parameters zijn om te versturen.

2. Transactie maken

In het volgende voorbeeld wordt een iDEAL transactie aangemaakt.

2.1. Lijst met banken ontvangen (iDEAL)

Met het volgende commando kunt u de lijst met banken ontvangen:
<?xml version="1.0" encoding="UTF-8"?>
<Transaction>
	 <Action>
		  <Name>IDEAL.GETBANKS
		  <Version>1
	 </Action>
	 <Merchant>
		  <ID>[Uw merchant ID]
		  <Key>[Uw merchant key]
		  <Checksum>[De checksum]
	 </Merchant>
</Transaction>
U krijgt hierop als antwoord:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
	 <Status>OK
	 <Banks>
		  <Bank>
			   <Name>ABN Amro
			   <Id>ABN_AMRO
		  </Bank>
		  [..]
	 </Banks>
</Response>
Het is om performance redenen aan te raden om deze gegevens te cachen op uw eigen server. Zet de TTL op 1 tot 2 dagen.

2.2 Transactie maken

<?xml version="1.0" encoding="UTF-8"?>
<Transaction>
	 <Action>
		  <Name>IDEAL.EXECUTE</Name>
		  <Version>1</Version>
	 </Action>
	 <Parameters>
		  <Amount>[Het bedrag, bijv: 10.99]</Amount>
		  <Currency>EUR</Currency>
		  <Bank>[Bank ID]</Bank>
		  <Description>[Order nummer]</Description>
		  <Return>[Return URL]</Return>
	 </Parameters>
	 <Merchant>
		  <ID>[Uw merchant ID]</ID>
		  <Key>[Uw merchant key]</Key>
		  <Checksum>[De checksum]</Checksum>
	 </Merchant>
</Transaction>
U kunt hierop het volgende antwoord krijgen:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
	 <Response>
		  <Status>OK</Status>
		  <TransactionID>[Transactie ID]</TransactionID>
		  <Code>[Transactie code]</Code>
		  <BankURL>[Bank URL]</BankURL>
	 </Response>
	 <Checksum>afd0c7e34f4282e05415d8dacbc6b359e7c1c6ea</Checksum>
</Response>
Let op de transactie ID en transactie code! Deze zijn nodig om de betaling te valideren nadat deze is gemaakt of geannuleerd. De gebruikers kunt u doorverwijzen naar de Bank URL. De banken staan niet toe dat u het betaalscherm toont in een frame of iframe.

2.3 Controleer de betaling

Wanneer de betaling is gedaan of is geannuleerd keert de gebruiker terug naar de Return URL (zie stap 2). Aan deze return URL wordt de volgende query string toegevoegd. http://www.uwreturnurl.nl/?id=[transaction_id]&status=[status]&salt=[salt]&checksum=[checksum]. Hiermee worden de volgende gegevens toegevoegd aan de URL:
  • De transactie ID
  • De status van de betaling (1 = betaald, 0 = mislukt)
  • Een Salt. Dit is een willekeurig nummer tussen de 10000 en 99999
  • Een checksum. Deze bestaat uit Transactie ID + Transactie Code + Status + Salt
U kunt de checksum herberekenen en vergelijken met de checksum uit de return URL. Wanneer deze gelijk zijn is de respons legitiem.

3. Betaalstatus controleren (alternatieve methode)

<?xml version="1.0" encoding="UTF-8"?>
<Transaction>
	 <Action>
		  <Name>TRANSACTIONSTATUS</Name>
		  <Version>1</Version>
	 </Action>
	 <Parameters>
		  <TransactionID>[Transactie ID]</TransactionID>
		  <TransactionCode>[Transactie Code]</TransactionCode>
	 </Parameters>
	 <Merchant>
		  <ID>[your id]</ID>
		  <Key>[your key]</Key>
		  <Checksum>[your checksum]</Checksum>
	 </Merchant>
</Transaction>
U kunt hierop het volgende antwoord krijgen:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
	 <Status>OK</Status>
	 <Transaction>
		  <Date>2013-02-11 16:24</Date>
		  <CurrentDate>2013-03-01 16:04</CurrentDate>
		  <ID>122</ID>
		  <Paid>Y</Paid>
		  <Definitive>Y</Definitive>
		  <MerchantID>[Uw merchant ID]</MerchantID>
		  <Consumer>
			   <Bank>RABONL2U</Bank>
			   <Name>[Tenaamstelling rekening consument]</Name>
			   <IBAN>[IBAN rekening consument]</IBAN>
		  </Consumer>
	 </Transaction>
</Response>

4. Product/klant details toevoegen aan uw call (PayPal en Achteraf betalen)

Voor de betaalmethoden Achteraf betalen en PayPal bent u verplicht om details van de consument en het product mee te sturen voor het aanmaken van een transactie. Door deze gegevens mee te sturen maakt u het mogelijk om extra services beschikbaar te stellen, waaronder customer protection (PayPal) en het versturen van facturen (Achteraf betalen). Voor alle andere betaalmethoden is dit niet verplicht. Er zijn drie belangrijke stappen voor het toevoegen van een product en de consument gegevens.

4.1 Product toevoegen aan de XML:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction>
	 <Action>
		  <Name>PAYPAL.EXECUTE</Name>
		  <Version>1</Version>
	 </Action>
	 <Parameters>
		  <Amount>0.01</Amount>
		  <Currency>EUR</Currency>
		  <Description>[Order number]</Description>
		  <Return>[Return URL]</Return>
	 </Parameters>
	 <Merchant>
		  <ID>[your id]</ID>
		  <Key>[your key]</Key>
		  <Checksum>[your checksum]</Checksum>
	 </Merchant>
	 <Products>
		  <Product>
			   <ID>2</ID>
			   <Description>testProduct</Description>
			   <Amount>1</Amount>
			   <Price>5</Price>
			   <Currency>EUR</Currency>
			   <Vat>21</Vat>
		  </Product>
		  <Product>
			   <ID>3</ID>
			   <Description>testProduct</Description>
			   <Amount>1</Amount>
			   <Price>5</Price>
			   <Currency>EUR</Currency>
			   <Vat>21</Vat>
		  </Product>
	 </Products>
</Transaction>

4.2 Consumentgegevens toevoegen aan de XML:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction>
	 <Action>
		  <Name>PAYPAL.EXECUTE</Name>
		  <Version>1</Version>
	 </Action>
	 <Parameters>
		  <Amount>0.01</Amount>
		  <Currency>EUR</Currency>
		  <Description>[Order number]</Description>
		  <Return>[Return URL]</Return>
	 </Parameters>
	 <Merchant>
		  <ID>[your id]</ID>
		  <Key>[your key]</Key>
		  <Checksum>[your checksum]</Checksum>
	 </Merchant>
	 <Products>
		  <Product>
			   <ID>2</ID>
			   <Description>testProduct</Description>
			   <Amount>1</Amount>
			   <Price>5</Price>
			   <Currency>EUR</Currency>
			   <Vat>21</Vat>
		  </Product>
		  <Product>
			   <ID>3</ID>
			   <Description>testProduct</Description>
			   <Amount>1</Amount>
			   <Price>5</Price>
			   <Currency>EUR</Currency>
			   <Vat>21</Vat>
		  </Product>
	 </Products>
	 <Customer>
		  <BirthDate>1947-09-28</BirthDate>
		  <City>Groningen</City>
		  <Email>support@qantani.com</Email>
		  <Familyname>Familyname</Familyname>
		  <Firstname>Firstname</Firstname>
		  <Gender>M</Gender>
		  <HouseExtension />
		  <HouseNumber>125</HouseNumber>
		  <ID>1</ID>
		  <Ip>46.122.18.158</Ip>
		  <PhoneNumber>0501234567</PhoneNumber>
		  <PostalCode>9999AA</PostalCode>
		  <Street>Hoofdstraat</Street>
		  <Type>Private</Type>
		  <CompanyName />
		  <ChamberOfCommerce/>
	 </Customer>
</Transaction>
In de volgende tabel vindt u een overzicht van de parameters voor het toevoegen van de consument details.
Parameter Verplicht? Omschrijving
BirthDate Ja Geboortedatum van de consument (JJJJ-MM-DD)
City Ja Stad consument (van factuuradres)
Email Ja e-mailadres consument (wordt gebruikt voor verzenden factuur)
Familyname Ja Achternaam (familienaam) consument
Firstname Ja Voornaam consument
Gender Ja Geslacht consument (M voor man, F voor vrouw)
HouseExtension Nee Toevoeging huisnummer consument (bijv. a of b)
HouseNumber Ja Huisnummer consument (bijv. 145)
ID Ja Interne consument ID (voor referentie)
IP Ja IP adres consument
PhoneNumber Ja Telefoonnummer consument (Alleen nummers! vervang + door 00 in geval van internationaal nummer)
PostalCode Ja Postcode consument (zonder spaties. Bijv. 1234XX)
Street Ja Straat consument
Type Ja Prive of bedrijf (Private of Company)
CompanyName Alleen als Type = Company Naam van bedrijf consument
ChamberOfCommerce Alleen als Type = Company KVK nummer van bedrijf consument
In de volgende tabel vindt u een overzicht van de parameters voor het toevoegen van (de) product(en).
Parameter Verplicht? Omschrijving
Amount Ja Aantal. Alleen hele getallen zonder decimalen
Currency Ja Valuta (standaard 'EUR')
Description Ja Omschrijving van het product
ID Ja Interne product ID (voor referentie)
Price Ja Prijs van het product. Bijvoorbeeld 19.50
Vat Ja BTW percentage (standaard 21). Alleen getal, bijvoorbeeld 13.50. Geen procentteken

4.3 Pas de berekenwijze van de checksum aan:

Voeg eerst alle parameters gesorteerd toe aan een string, zoals uitgelegd in paragraaf "1.3 Checksum genereren". Sorteer vervolgens de parameters van elk product op basis van de Node naam. Voeg vervolgens de parameters toe aan het einde van de string. Let op dat de volgorde van de producten hetzelfde blijft als in de XML. Sorteer vervolgens de parameters van de consument op basis van de Node naam. Voeg vervolgens de parameters toe aan het einde van de string.

Overzicht functies

Functie Parameters Uitvoer
ideal.getbanks - Lijst met banken voor iDEAL
ideal.execute
  • Bank
  • Amount
  • Currency
  • Return
  • Description
URL om consument naar door te verwijzen voor uitvoeren van de betaling, TransactionID en TransactionCode.
paypal.execute
  • Amount
  • Currency
  • Return
  • Description
  • [Products]
URL om consument naar door te verwijzen voor uitvoeren van de betaling, TransactionID en TransactionCode.
sofort.execute
  • Amount
  • Currency
  • Return
  • Description
URL om consument naar door te verwijzen voor uitvoeren van de betaling, , TransactionID en TransactionCode.
cc.execute
  • Amount
  • Currency
  • Return
  • Description
URL om consument naar door te verwijzen voor uitvoeren van de Creditcard betaling, TransactionID en TransactionCode.
bitpay.execute
  • Amount
  • Currency
  • Return
  • Description
URL om consument naar door te verwijzen voor uitvoeren van de betaling, TransactionID en TransactionCode.
paylater.execute
  • Amount
  • Currency
  • Return
  • Description
  • [Products]
URL om consument naar door te verwijzen voor uitvoeren van de betaling, TransactionID en TransactionCode.
paylater.check
  • Amount
  • Currency
  • Return
  • Description
  • [Products]
OK of NOT OK
GetPaymentMethods - Lijst met beschikbare betaalmethoden
TRANSACTIONSTATUS
  • TransactionID
  • TransactionCode
Status van de transactie.Y = betaald, N = niet betaald.
REFUND
  • TransactionID
  • Amount
  • TransactionCode
OK bij succesvolle refund.

Overzicht parameters

Parameter Omschrijving
Bank De ID van de bank, bijvoorbeeld ABN_AMRO
Checksum Zie in de API documentatie de paragraaf "Checksum genereren" voor de opbouw van deze sha1 string.
Currency De munteenheid van uw transactie bedrag. Alleen betalingen in Euro's kunnen worden uitgevoerd. Gebruik hiervoor de code EUR
Description De omschrijving van de transactie. Maximaal 30 tekens!
ID Hier volgt uw merchant ID. Deze ID ontvangt, of heeft u ontvangen na de verificatie van uw account. U kunt deze ook terugvinden bij uw account onder instellingen.
Key Hier volgt uw merchant key. Deze key ontvangt, of heeft u ontvangen na de verificatie van uw account. U kunt deze ook terugvinden bij uw account onder instellingen.
Name De functienaam die wordt aangeroepen. Zie de tabel "Overzicht functies".
Return De URL waar de bezoeker naar wordt doorverwezen na het voltooien van de betaling via iDeal / de website van de bank. Voeg aan deze url de volgende query string toe: ?id=[transaction_id]&status=[status]&salt=[salt]&checksum=[checksum]
Secret Hier volgt uw merchant secret. Deze secret ontvangt, of heeft u ontvangen na de verificatie van uw account. U kunt deze ook terugvinden bij uw account onder instellingen.
TransactionCode De code van de transactie. Deze krijgt u in de respons nadat u een transactie heeft gemaakt.
TransactionID De unieke ID van de transactie. Deze krijgt u in de respons nadat u een transactie heeft gemaakt.
Version Het versienummer van de API. De huidige versie is 1.