web.html.api_gh.html Maven / Gradle / Ivy
BitMerchant
Introduction
Bitmerchant includes a powerful REST API to accept payments for your business.
It allows you to:
- Accept bitcoin payments on your website
- Create items for sale, in your native currency
- Create buttons and payment iframes, with qr codes
- Refund orders, in any currency.
Bitmerchant works using the BIP70 protocol, meaning full compatibility with wallets such as bitcoin-qt, and the android-wallet. You may also use the Button generator tool to dynamically create payment buttons.
API endpoint
http://localhost:4567/api/
Currencies
Currencies supported
A list of the currencies supported.
- Historical and spot-rate conversions are taken from BitcoinAverage.com
- Currency conversion rates are updated every 5 minutes
- Currencies include : BTC, AUD, BRL, CAD, CHF, CNY, EUR, GBP, HKD, IDR, ILS, MXN, NOK, NZD, PLN, RON, RUB, SEK, SGD, TRY, USD, and ZAR
GET http://localhost:4567/api/currencies
Example response
{
"currencies" : [ {
"currency" : {
"desc" : "Bitcoin",
"iso" : "BTC",
"unicode" : "฿"
}
}, {
"currency" : {
"desc" : "Australian Dollar",
"iso" : "AUD",
"unicode" : "$"
}
}, {
"currency" : {
"desc" : "Brazilian Real",
"iso" : "BRL",
"unicode" : "R$"
}
}, ...
A button represents a consistent item for sale, like kitten mittens. On Bitmerchant, orders do not exist by themselves. There are two main models:
- Buttons
- Orders
A button has many orders. An order belongs to one button.This endpoint creates a payment button, page, or iFrame to accept bitcoin on your website.
POST http://localhost:4567/api/create_button
Example request
{
"button" : {
"name": "kitten mittens",
"type": "buy_now",
"style": "custom_large",
"network": "test",
"text": "Buy with USD",
"price_string": "5",
"price_currency_iso": "USD",
"callback_url": "http://www.example.com/my_custom_button_callback",
"description": "Is your cat making too much noise all the time?"
}
}
Example response
{
"button" : {
"callback_url" : "http://www.example.com/my_custom_button_callback",
"created_at" : 1421459084840,
"description" : "Is your cat making too much noise all the time?",
"id" : 9,
"name" : "kitten mittens",
"native_currency_iso" : "USD",
"price_1" : null,
"price_2" : null,
"price_3" : null,
"price_4" : null,
"price_5" : null,
"price_select" : 0,
"style" : "custom_large",
"text" : "Buy with USD",
"total_native" : 5,
"type" : "buy_now",
"variable_price" : 0
}
}
Parameter
Type
Required
Description
button
hash
Required
Button object containing the following params
button[name]
string
Required
The name of the item.
button[price_string]
string
Required
The price of the item.
button[price_currency_iso]
string
Required
The currency you are selling the item for, such as BTC, USD, EUR...
Use http://localhost/currencies/ to get a list of currencies.
button[type]
string
Optional
One of buy_now and donation. Default is buy_now.
button[style]
string
Optional
One of buy_now_large, buy_now_small, donation_large, donation_small and none. Default is buy_now_large. none is used if you plan on triggering the payment modal yourself using your own button or link.
button[network]
string
Optional
Either main or test.
button[text]
string
Optional
Allows you to customize the button text on <b>custom_large</b> and <b>custom_small</b> styles. Default is <i>Pay With Bitcoin.</i>
button[description]
string
Optional
A longer description of the item
button[callback_url]
string
Optional
A custom callback URL specific to this button.
button[variable_price]
string
Optional
Setting this parameter to <b>true</b> will allow the user to choose a variable price.
button[price_select]
string
Optional
Show some suggested prices
button[price_1]
string
Optional
A suggested price
button[price_2]
string
Optional
A suggested price
button[price_3]
string
Optional
A suggested price
button[price_4]
string
Optional
A suggested price
button[price_5]
string
Optional
A suggested price
Lets you retrieve an individual button.
GET http://localhost:4567/api/buttons/:id
Example response
{
"button" : {
"callback_url" : "http://www.example.com/my_custom_button_callback",
"created_at" : 1421459084840,
"description" : "Is your cat making too much noise all the time?",
"id" : 1,
"name" : "kitten mittens",
"native_currency_iso" : "USD",
"price_1" : null,
"price_2" : null,
"price_3" : null,
"price_4" : null,
"price_5" : null,
"price_select" : 0,
"style" : "custom_large",
"text" : "Buy with USD",
"total_native" : 5,
"type" : "buy_now",
"variable_price" : 0
}
}
Shows you a list of the buttons
GET http://localhost:4567/api/buttons
Example response
{
"buttons" : [ {
"button" : {
"callback_url" : "http://www.example.com/my_custom_button_callback",
"created_at" : 1421348879168,
"description" : "A derpy shoe",
"id" : 1,
"name" : "derpsho3e",
"native_currency_iso" : "USD",
"price_1" : null,
"price_2" : null,
"price_3" : null,
"price_4" : null,
"price_5" : null,
"price_select" : 0,
"style" : "custom_large",
"text" : "Buy with USD/BTC",
"total_native" : 0.51,
"type" : "buy_now",
"variable_price" : 0
}
}, ...
Shows you a list of orders for a given button. Orders with a status of new will not be shown.
GET http://localhost:4567/api/buttons/:button_id/orders
Example response
{
"orders" : [ {
"order" : {
"button_description" : "A derpy shoe",
"button_id" : 1,
"button_name" : "derpsho3e",
"created_at" : 1421348881482,
"expire_time" : 1421349481481,
"id" : 1,
"memo" : "A derpy shoe",
"merchant_data" : "DickTowel.com",
"native_currency_iso" : "USD",
"network" : "test",
"payment_request_url" : "bitcoin:mxJRbqzkAgCXJrzfGDGLCvPTa87fgmYoLT?r=http://123.456.7.8:4567/payment_request/9&amount=0.00257004",
"payment_url" : "http://96.28.13.51:4567/create_payment/1",
"receive_address" : "myr8GW8n6QnGGgkmXGa29otvBV9354wx3L",
"status" : "new",
"total_native" : 0.51,
"total_satoshis" : 233912,
"transaction_hash" : null
}
}, ...
Lets you generate an order associated with a button. After generating an order, a BIP70 payment request is created, located at the payment_request_url.
The status of this newly created order will be new, but can be updated later on. See orders for more information.
The custom_native_price field is used when creating orders from buttons with price selections, and/or a custom price field.
POST http://localhost:4567/api/buttons/:id/create_order or POST /api/buttons/:button/create_order/:custom_native_price
Example response
{
"order" : {
"button_description" : "Dick Towel",
"button_id" : 1,
"button_name" : "Dick Towel",
"created_at" : 1421519994997,
"expire_time" : 1421520594997,
"id" : 9,
"memo" : "nothing here",
"merchant_data" : "DickTowel.com",
"native_currency_iso" : "USD",
"network" : "test",
"payment_request_url" : "bitcoin:mxJRbqzkAgCXJrzfGDGLCvPTa87fgmYoLT?r=http://123.456.7.8:4567/payment_request/9&amount=0.00257004",
"payment_url" : "http://123.456.7.8:4567/create_payment/1",
"receive_address" : "mxJRbqzkAgCXJrzfGDGLCvPTa87fgmYoLT",
"status" : "new",
"total_native" : 0.51,
"total_satoshis" : 257004,
"transaction_hash" : null
}
}
Orders
List orders
Gives a merchant’s orders that they have received. An order can have any of the following statuses:
- new - The order was just created
- completed - The order has been completed
- cancelled - The order was cancelled
- overpaid - An over payment was received
- underpaid - An underpayment was received
- refunded - The order was refunded
- expired - No payment was received in the 10-minute time period
The transaction_hash can be used to link an order to a transaction.
Orders with a status of new will not be shown.
GET http://localhost:4567/api/orders
Example response
{
"orders" : [ {
"order" : {
"button_description" : "A derpy shoe",
"button_id" : 1,
"button_name" : "derpsho3e",
"created_at" : 1421348881482,
"expire_time" : 1421349481481,
"id" : 1,
"memo" : "A derpy shoe",
"merchant_data" : "DickTowel.com",
"native_currency_iso" : "USD",
"network" : "test",
"payment_request_url" : "bitcoin:mxJRbqzkAgCXJrzfGDGLCvPTa87fgmYoLT?r=http://123.456.7.8:4567/payment_request/9&amount=0.00257004",
"payment_url" : "http://96.28.13.51:4567/create_payment/1",
"receive_address" : "myr8GW8n6QnGGgkmXGa29otvBV9354wx3L",
"status" : "new",
"total_native" : 0.51,
"total_satoshis" : 233912,
"transaction_hash" : null
}
}, ...
Create an order
This is a shortcut that does two things:
- Creates a button
- Creates an order for that button
The request you provide is exactly like the request for a button.
A button represents a consistent item for sale, like kitten mittens. On Bitmerchant, orders do not exist by themselves. There are two main models:
- Buttons
- Orders
A button has many orders. An order belongs to one button.
POST http://localhost:4567/api/create_order
Example request
{
"button" : {
"name": "kitten mittens",
"type": "buy_now",
"style": "custom_large",
"network": "test",
"text": "Buy with USD",
"price_string": "5",
"price_currency_iso": "USD",
"callback_url": "http://www.example.com/my_custom_button_callback",
"description": "Is your cat making too much noise all the time?"
}
}
Example response
{
"order" : {
"button_description" : "A derpy shoe",
"button_id" : 1,
"button_name" : "derpsho3e",
"created_at" : 1421348881482,
"expire_time" : 1421349481481,
"id" : 1,
"memo" : "A derpy shoe",
"merchant_data" : "DickTowel.com",
"native_currency_iso" : "USD",
"network" : "test",
"payment_request_url" : "bitcoin:mxJRbqzkAgCXJrzfGDGLCvPTa87fgmYoLT?r=http://123.456.7.8:4567/payment_request/9&amount=0.00257004",
"payment_url" : "http://96.28.13.51:4567/create_payment/1",
"receive_address" : "myr8GW8n6QnGGgkmXGa29otvBV9354wx3L",
"status" : "new",
"total_native" : 0.51,
"total_satoshis" : 233912,
"transaction_hash" : null
}
}
Parameter
Type
Required
Description
button
hash
Required
Button object containing the following params
button[name]
string
Required
The name of the item.
button[price_string]
string
Required
The price of the item.
button[price_currency_iso]
string
Required
The currency you are selling the item for, such as BTC, USD, EUR...
Use http://localhost/currencies/ to get a list of currencies.
button[type]
string
Optional
One of buy_now and donation. Default is buy_now.
button[style]
string
Optional
One of buy_now_large, buy_now_small, donation_large, donation_small and none. Default is buy_now_large. none is used if you plan on triggering the payment modal yourself using your own button or link.
button[network]
string
Optional
Either main or test.
button[text]
string
Optional
Allows you to customize the button text on <b>custom_large</b> and <b>custom_small</b> styles. Default is <i>Pay With Bitcoin.</i>
button[description]
string
Optional
A longer description of the item
button[callback_url]
string
Optional
A custom callback URL specific to this button.
button[variable_price]
string
Optional
Setting this parameter to <b>true</b> will allow the user to choose a variable price.
button[price_select]
string
Optional
Show some suggested prices
button[price_1]
string
Optional
A suggested price
button[price_2]
string
Optional
A suggested price
button[price_3]
string
Optional
A suggested price
button[price_4]
string
Optional
A suggested price
button[price_5]
string
Optional
A suggested price
Show an order
Lets you retrieve an individual order.
GET http://localhost:4567/api/orders/:id
Example response
{
"order" : {
"button_description" : "A derpy shoe",
"button_id" : 1,
"button_name" : "derpsho3e",
"created_at" : 1421348881482,
"expire_time" : 1421349481481,
"id" : 1,
"memo" : "A derpy shoe",
"merchant_data" : "DickTowel.com",
"native_currency_iso" : "USD",
"network" : "test",
"payment_request_url" : "bitcoin:mxJRbqzkAgCXJrzfGDGLCvPTa87fgmYoLT?r=http://123.456.7.8:4567/payment_request/9&amount=0.00257004",
"payment_url" : "http://96.28.13.51:4567/create_payment/1",
"receive_address" : "myr8GW8n6QnGGgkmXGa29otvBV9354wx3L",
"status" : "new",
"total_native" : 0.51,
"total_satoshis" : 233912,
"transaction_hash" : null
}
}
Refund an order
Lets you refund an order, at either a specific amount and currency, or in its original native currency and amount
POST http://localhost:4567/api/refund/:order
Or
http://localhost:4567/api/refund/:order/:amount/:currency
Example response
Order succesfully refunded
Parameter
Type
Required
Description
order
string
Required
The order number
amount
string
Required
The refund amount as a string
currency
string
Required
The native refund currency