BitKassa API documentatie (v0.42 NL)

(Also available in English)

1. Een betaling verwerken in het kort

  1. Roep de BitKassa API aan om een betaling te initiëren. Wij retourneren o.a. een URL naar een betaalpagina en een Bitcoin-adres en bedrag.
  2. Ofwel je redirect de klant door naar onze betaalpagina, ofwel je toont zelf een betaalpagina met het gegeven Bitcoin-adres en bedrag in bitcoins.
  3. Indien je onze betaalpagina gebruikt, redirecten wij de klant na de betaling weer terug naar je site of webshop, inclusief resultaat van de betaling.
  4. Daarnaast roepen wij een optionele callback URL aan waar we de status van de betaling doorgeven.

2. Technische specificaties

Bij het aanmaken van een BitKassa account krijg je een merchant ID en een secret API key (beide een alfanumerieke string).

Voor iedere API call roep je deze URL aan:

  https://www.bitkassa.nl/api/v1

met twee POST of GET parameters:

  p = base64-encoded json data
  a = authenticatie hash

Waarbij a = sha256( secret API key + json data + unixtime ) + unixtime

De json data moet altijd een element action bevatten met de API-functie die je wilt aanroepen, en een merchant_id met je merchant ID. De overige json data (verplicht of optioneel) hangt af van de action, zie onder. Unixtime is de huidige unix timestamp als integer. De + staat voor string concatenation (dus achter elkaar plakken).

Merk op:

3. Een betaling starten

Om een betaling te starten roep je de API aan met de volgende json data: (* = verplicht)
NaamTypeOmschrijvingVoorbeeld
action *stringDe API functionaliteit die je wilt aanroepen, in dit geval "start_payment"start_payment
merchant_id *stringJe merchant IDbanketbakkerhenk
currency *stringDe valuta van het te betalen bedrag (kan EUR of BTC zijn)EUR
amount *integerHet te betalen bedrag in centen of satoshi's1295
descriptionstringOmschrijving van het product of de betaling voor de klantChocoladetaart XL
return_urlstringDe URL waar wij de klant heen sturen na de betaling (als je onze betaalpagina gebruikt)https://www.bakkerhenk.nl/webshop/return.php
update_urlstringEen callback URL die wij aanroepen als de status van de betaling verandert (zie onder)https://www.bakkerhenk.nl/update_order.php
meta_infostringEen eigen referentie, bijvoorbeeld een ID in je eigen database, die wij meesturen met status updatesA947183352

De API call geeft een json resultaat terug, bij succes is dat:
NaamTypeOmschrijvingVoorbeeld
payment_idstringOnze ID voor deze betalingdhqe4cnj7f
payment_urlstringDe URL waar je de klant heen kunt sturen (als je onze betaalpagina wilt gebruiken)https://www.bitkassa.nl/tx/dhqe4cnj7f
addressstringHet Bitcoin-adres waar de klant het bedrag naartoe moet sturen1BK9imjqeziWixvD64XfYNye5rKi2HcN7P
amountintegerHet bedrag in satoshi's dat de klant moet betalen410000
bitcoin_urlstringEen complete Bitcoin-URL die je kunt tonen (als klikbare link en/of QR) waarmee de klant kan betalen vanuit zijn wallet (als je je eigen betaalpagina wilt hosten)bitcoin:1BK9imjqeziWixvD64XfYNye5rKi2HcN7P?amount=0.0041
expireintegerUnix timestamp wanneer de betaling verloopt (in principe 15 minuten na aanvang)1548037400
successbooleanBevestiging dat de API call correct is verwerkttrue
En anders:
NaamTypeOmschrijvingVoorbeeld
errorstringReden waarom de betaling niet kon worden gestartMissing amount
successbooleanIndicatie dat de API call niet correct is verwerktfalse

Bijvoorbeeld, je stuurt:
{
 "action":       "start_payment",
 "merchant_id":  "schoenmakerpiet",
 "currency":     "EUR",
 "amount":       2250
}

Onze API geeft terug:
{
 "payment_id":    "r6fhp22x5c",
 "payment_url":   "https://www.bitkassa.nl/tx/r6fhp22x5c",
 "address":       "1BK9imjqeziWixvD64XfYNye5rKi2HcN7P",
 "amount":        720000,
 "bitcoin_url":   "bitcoin:1BK9imjqeziWixvD64XfYNye5rKi2HcN7P?amount=0.0072",
 "expire":        1548037400,
 "success":       true
}

4. Resultaat van een betaling verwerken

Indien je bij een betaling een update_url had meegegeven, roepen wij die aan wanneer de status van een order verandert. Dat doen we net als onze eigen API calls met twee POST parameters p en a, waarbij p een base64-encoded json object is, en a een authenticatie hash (op dezelfde manier gedefinieerd als hierboven, dit ter verificatie dat de callback echt van ons komt).

Indien je bij een betaling een return_url had meegegeven, redirecten we de de klant daarheen vanaf onze betaalpagina (nadat de betaling is voldaan of geannuleerd). Ook daarbij sturen we diezelfde twee parameters mee met de status van de betaling.

De json data (de p parameter) bij zo'n callback of redirect bevat:
NaamTypeOmschrijvingVoorbeeld
payment_idstringDe ID van de betaling waarvan we een update sturen of waarvandaan we de klant redirectendhqe4cnj7f
payment_statusstringDe status van de betaling (zie onder)pending
meta_infostringJe eigen referentie string, indien je die had meegegeven bij het starten van de betalingA947183352

Bijvoorbeeld, bij het aanroepen van de update_url en/of het redirecten van de klant naar return_url sturen wij mee:
{
 "payment_id":      "r6fhp22x5c",
 "payment_status":  "paid"
}

Let op dat je de authenticatie hash (de a parameter) verifieert, anders zou iemand kunnen proberen om zelf zijn betalingsstatus naar 'paid' te veranderen. Zie ook het PHP voorbeeld 'Wrapper functie om de POST parameters te lezen' onderaan.

5. Status van betaling

De status van een betaling kan het volgende zijn:
StatusOmschrijving
openDe betaling is net gestart en staat nog open, er heeft nog geen transactie plaatsgevonden
cancelledDe klant heeft de betaling geannuleerd
expiredDe betaling is verlopen (er zijn geen bitcoins verstuurd binnen de vereiste tijd)
pendingEr is een betaling onderweg, je kunt de klant eventueel informeren dat de betaling onderweg is en dat de bestelling wordt verwerkt zodra de transactie is bevestigd door het Bitcoin-netwerk
paidDe betaling is confirmed door het Bitcoin-netwerk, je kunt het product sturen of de dienst leveren

Een betaling begint altijd als open, en verandert naar cancelled als de klant annuleert, of expired als de klant te lang wacht en niets doet (of zijn browser afsluit), of pending zodra de klant zijn Bitcoin-betaling verstuurt. Na pending verandert de status vanzelf naar paid zodra er een confirmation (bevestiging) is van het Bitcoin-netwerk. In extreme gevallen waar de betaling niet binnen afzienbare tijd is confirmed en het onwaarschijnlijk is dat dit verandert, verandert de status alsnog naar expired. Zodra de status van een betaling eenmaal paid, cancelled, of expired is, verandert hij nooit meer.


Let op - wij garanderen pas uitbetaling als de status paid wordt, dus na een confirmation van het Bitcoin netwerk. Of dit gebeurt en hoe lang dit duurt heeft te maken met hoe druk het op het netwerk is en hoeveel fee de betalende klant bij zijn Bitcoin-transactie doet. Dit varieert tussen enkele minuten tot enkele weken, het is ook mogelijk dat een order te lang blijft hangen en nooit meer bevestigd wordt. Wij raden aan om zodra een betaling pending is, de klant te informeren "dank voor uw betaling, zodra uw transactie een bevestiging heeft gekregen van het Bitcoin-netwerk wordt uw order verwerkt", en daadwerkelijk de dienst te leveren of product te versturen zodra de status naar paid verandert.

6. Status van een betaling opvragen

Behalve de status die wij doorsturen naar de return_url en update_url kun je ook zelf de status van een betaling opvragen, via een API call met de volgende json data: (* = verplicht)
NaamTypeOmschrijvingVoorbeeld
action *stringDe API functionaliteit die je wilt aanroepen, in dit geval "get_payment_status"get_payment_status
merchant_id *stringJe merchant IDbanketbakkerhenk
payment_id *stringDe ID van de betalingdhqe4cnj7f

Het resultaat dat je terugkrijgt bevat:
NaamTypeOmschrijvingVoorbeeld
payment_statusstringDe status van de betaling (zie boven)paid
successbooleanBevestiging dat de API call correct is verwerkttrue
Of als er een fout optrad:
NaamTypeOmschrijvingVoorbeeld
errorstringReden waarom de status van de betaling niet kon worden opgevraagdInvalid payment_id
successbooleanIndicatie dat de API call niet correct is verwerktfalse

Bijvoorbeeld, je stuurt:
{
 "action":       "get_payment_status",
 "merchant_id":  "schoenmakerpiet",
 "payment_id":   "r6fhp22x5c"
}

Onze API geeft terug:
{
 "payment_status":  "paid",
 "success":         true
}

Merk op dat het zelf opvragen van een betalingsstatus in principe niet noodzakelijk is, de status die wij doorgeven via de update_url en/of return_url (waarvan je er in de praktijk waarschijnlijk één of allebei meegeeft) is op zich voldoende om een betaling volledig te verwerken.


7. PHP voorbeelden

Wrapper functie om BitKassa API aan te roepen:
function CallBitKassaApi( $action, $params )
{
	$merchantId = 'banketbakkerhenk';
	$secretApiKey = 'abcde12345';

	// voeg action en merchant_id (vereist voor elke API call) toe aan de params array
	$params['action'] = $action;
	$params['merchant_id'] = $merchantId;

	// creeer json en authenticatie
	$jsonData = json_encode($params);
	$t = time();
	$a = hash('sha256',$secretApiKey.$jsonData.$t).$t; // authenticatie hash
	$p = base64_encode($jsonData);

	// roep API url (zou ook kunnen met curl e.d.)
	$jsonResult = file_get_contents("https://www.bitkassa.nl/api/v1?p=$p&a=$a");

	// retourneer resultaat als array (of breek af met foutmelding)
	if (!$jsonResult) die('Kon geen verbinding krijgen');
	$result = json_decode($jsonResult,true);
	if (!$result['success']) die('Error: '.$result['error']);
	return $result;
}
Betaling starten:
$params = array(
	// verplicht:
	'currency' => 'EUR',
	'amount'   => 1295,

	// optioneel:
	'description' => 'Chocoladetaart XL',
	'return_url'  => 'https://www.bakkerhenk.nl/webshop/landingpage.php',
	'update_url'  => 'https://www.bakkerhenk.nl/update_order.php',
	'meta_info'   => '123456789', // kan bijvoorbeeld een order of klant ID zijn in je eigen database, voor je eigen referentie
);

$result = CallBitKassaApi('start_payment',$params);

// stuur klant door naar betaalpagina
header('Location: '.$result['payment_url']);
Status van een betaling opvragen:
$params = array( 'payment_id' => 'abcdefghijk' );
$result = CallBitKassaApi('get_payment_status',$params);

print('De status van uw betaling is: '.$result['payment_status']);
Wrapper functie om de POST parameters te lezen die wij meesturen met een callback of redirect:
function GetBitKassaParams()
{
	$mySecretApiKey = 'abcde12345';
	$p = $_POST['p'];
	$a = $_POST['a'];
	$jsonData = base64_decode($p);

	// controleer authentication hash (zodat je zeker weet dat deze request echt van ons kwam,
	// en niet van iemand die zijn order ten onrechte op 'paid' probeert te zetten)
	$t = substr($a,64);
	$verify = hash('sha256',$mySecretApiKey.$jsonData.$t).$t;
	if ($a!=$verify) die('Authentication error');

	return json_decode($jsonData,true);
}
Callback script dat je zou kunnen meegeven als update_url:
$params = GetBitKassaParams();

$paymentId = $params['payment_id'];
$status = $params['payment_status'];
$myRef = $params['meta_info'];

if ($status=='paid')
{
	// (...verstuur product...)
}
Terugkeer pagina die je zou kunnen meegeven als return_url, waarheen wij de klant redirecten na de betaling:
$params = GetBitKassaParams();

$paymentId = $params['payment_id'];
$status = $params['payment_status'];
$myRef = $params['meta_info'];

if ($status=='pending' || $status=='paid')
{
	print('Dank voor uw betaling, zodra deze een bevestiging vanuit het Bitcoin-netwerk krijgt gaan we uw order zo snel mogelijk verwerken!');
}
else if ($status=='expired') print('Er is geen betaling ontvangen :(');
else if ($status=='cancelled') print('U heeft de betaling geannuleerd :(');



Vragen? Laat het ons weten!