Payment Service API

Version 2013-03-01, status: v0.6

Bitmymoney offers a webservice for Bitcoin payments in webshops. This document describes the API calls needed for payment integration.

 

All calls should be made relative to:

https://bitmymoney.com/secure/pay/

you can generate a demo payment at:
https://bitmymoney.com/secure/pay/demo/ 

Signing a request

In some calls we demand the request to be signed with the Bitmymoney apikey given to the merchant. We use the HMAC algorithm with SHA256 as hash function: sign = hmac(apikey, message, sha256).hexdigest()

If a nonce has been provided, we will append it to the message.

 

A Python example:

import hashlib, hmac
apikey = u"test"

data = u"message"

sign = hmac.new(str(apikey), str(data), hashlib.sha256).hexdigest()
sign == '61d947ddeaabcbbfc1681b542fa62fcc96350bd2866eeae0fd6d0693b37d4cb7'

nonce = 928374651  # with valid integer nonce

sign = hmac.new(str(apikey), str(data)+str(nonce), hashlib.sha256).hexdigest()
sign == '69bc013d59f5faef10cec9752b95c262f4a4d7fa73428b3ff21850d26c1c0de3'

 

Price in BTC

Returns the price in bitcoins for the given amount in euro's.

request GET

     /price_btc?amount_eur=...&decimals=2

response JSON

     <amount in BTC as a Decimal>

parameters

     amount_eur     The amount to be calculated in BTC. This value will be interpreted as a decimal.

   optional

     decimals          The number of decimals for the price to be rounded to. When omitted, it will be set to 5 by default.

Example

     /price_btc?amount_eur=180.99&decimals=2

Response

Example

     /price_btc?amount_eur=3.1415927

Response

     "0.17506"

Start transaction

Request a unique payment URL from Bitmymoney. The user should be redirected to this URL to complete the order.

Pass url_success as the address for Bitmymoney to redirect the user to after a successful payment

Pass callback_success for Bitmymoney to notify your webshop software of a successful payment and callback_failure for failed payments. A callback will be tried up to four times by our backend. 

request GET

     /start?amount_eur=...&url_success=...&merchant_id=&sign=...&nonce=...

response JSON (used 'test' as apikey in this example and no nonce)

      {"url_pay": "/secure/pay/tx/c60a5daf780ea6e/",
       "btc_address": "1JustANaweSoMeExampLeAddrEsS",
       "url_qrcode": "/secure/pay/tx/c60a5daf780ea6e/qrcode.png",

       "url_status": "/secure/pay/tx/c60a5daf780ea6e/status",
       "sign": "c9f86d227a5908fcdb72fcd21db97d871218e2a9490ea260483ff2d321720d8b"}

parameters

   required:

     amount_eur    Amount to pay in EUR

     description     Description of order (max. 255 characters) 

     url_success    URL to redirect the user to  after a successful payment

     merchant_id   Your Bitmymoney user id

     sign                sign("<amount_eur><description><url_success><merchant_id>")

   optional:

     order_id         Value can be chosen by the merchant to be used for reference to an order (max. 31 characters) 

     url_failure       URL to redirect the user to after a failed or cancelled payment 

     callback_success   URL Bitmymoney calls to notify webshop of successful payment. If this parameter is omitted, we will call url_success

     callback_failure      URL Bitmymoney calls to notify webshop of failed payment 

     nonce             Random integer you provide, Bitmymoney will use it when signing the response for extra security  

response (used 'test' as apikey in this example)

     url_pay           The URL for the user to be redirected to

     btc_address   Bitcoin address used exclusively for this transaction 

     url_qrcode     URL to the QR code PNG for the Bitcoin payment

     url_status       The URL the webshop can use to request the status of the transaction (see Transaction status) 

     sign                sign("<url_pay><btc_address><url_qrcode><url_status><your nonce>)

On starting a transaction Bitmymoney will generate a BTC address exclusively for this transaction. The requested BTC amount is calculated from the EUR amount with the current Bitcoin price.

Callback

Bitmymoney will notify the webshop by calling the callback given by the merchant in the Start call. It will be called on all statuses except OPEN and UNCONFIRMED. Be sure only to accept status SUCCESS as a successful payment.

 

The call will pass JSON POST data containing:

   {'order_id': u'Bitmymoney demo',
    'status': 'CANCELLED',
    'amount_eur': Decimal('0.01'),
    'txid': u'c635f4c29a324f4',
    'sign': 'b9f53e3684371140a937c0180a3753f2cfa59aaac6c580e32cd1992a02be4ce7',}

POST parameters

     amount_eur   Amount to pay in EUR

     order_id         Value given by the merchant as a reference (max. 31 characters) 

     txid                 Bitmymoney transaction id

     status             of the transaction

     sign                sign("<txid><order_id><amount_eur><status>")

Payment page

On this page the end user will be requested to make a bitcoin payment. All payment details relevant to the transaction will be shown. The payment page URL can be requested using the /start call.

request GET

     /tx/<txid>

response

     a HTML page

parameters

     None. The Bitmymoney transaction id (txid) is part of the URL. This txid is unique.

 

This page will inform the user of the status of the payment. Only of the status is OPEN, payment details will be shown. In other situations, the user will be informed why payment is not possible. For example the time limit might have passed, resulting in an EXPIRED status.

Transaction status

Vraag de status van de transactie op. Mogelijke antwoorden: OPEN, SUCCESS, CANCELLED, EXPIRED, FAILURE or ERROR.

request GET

     /tx/<transaction id>/status?nonce=...

response JSON (used 'test' as apikey in this example, nonce=1362131889344)

     {"status": "OPEN",
      "amount_received": "0.00000000",
      "amount_btc": "0.00050000",
      "txid": "c60135f69b072fb",

      "sign": "a2790f299526c8018bc55ed7ad6876aaa00e85cd22227893db5cc709eb87fdb2"}

parameters

   optional

     jsonp      Function name for the result to be wrapped in

     nonce     Random integer you provide, Bitmymoney will use it when signing the response for extra security   

response

     sign        sign("<status><amount_btc><amount_received><txid><nonce>")

 

Response prices should be interpreted as decimals. The status will change to UNCONFIRMED when amount_received is equal to or larger than amount_btc. After 2 confirmations, the status will be set to SUCCESS and the callback to the webshop will be called. Be sure only to accept status SUCCESS as a successful payment.
The status is EXPIRED If the user has failed to pay within the time limit.  

Example

     /tx/c60135f69b072fb/status?nonce=1362131889344

Response JSON (used 'test' as apikey in this example)

     {"status": "EXPIRED", "amount_received": "0.00000000", "amount_btc": "0.00560000", "txid": "c60135f69b072fb"
      "sign": "8472afa6863376af2abb0c4b1289f2132237a31e3b3439736c7b235c1f2cb776"}

Example

     /tx/c60135f69b072fb/status?jsonp=callback&nonce=

Response JSONP (used 'test' as apikey in this example, no nonce)

     callback({"status": "UNCONFIRMED", "amount_received": "2.30000000", "amount_btc": "2.30000000", "txid": "c60135f69b072fb",
      "sign": "9182a4c384405036fd42c6d3f5f75d773adec18cdfd0d813f338f81e2fd12804"})

Transaction QR Code

Generate the QR code for the given Bitmymoney transaction.

request GET

     /tx/.../qrcode.png

response PNG

     <binary data>

parameters

     txid     Bitmymoney transaction ID in the URL path

Example usage in HTML

     <img src="https://bitmymoney.com/secure/pay/tx/123abc456def789/qrcode.png" alt="bitcoin uri qrcode" />