GitHub - Paymium/old-api-documentation: Deprecated see https://github.com/Paymium/api-documentation

NEW: Our sandbox environment is now available, visit sandbox.paymium.com (you may have to add a security exception for the SSL certificate to validate).

The Paymium API allows developers to extend the capabilities of the Paymium platform, from reading the latest ticker to automating trades with bots.

IMPORTANT NOTE: Your API client must support SNI in order to not receive certificate name mismatch warnings.

Is is possible to, among other things:

Access public data (ticker, asks, bids, trades, etc...)
Authenticate users with their permission using OAuth2 *
Access authenticated user balances, trades, and other data *
Automate trading *

* Authenticating users is only available to developers that have a fully verified and approved Paymium account. On the other hand, public data is available to everyone

General information

Formats and required HTTP request headers

The API will only answer with JSON or empty responses. It expects parameters to be passed in JSON with the correct Content-Type: application/json being set.

Localization

The relevant results and error messages will be localized to the language associated to the user, currently English and French are supported.

Datetime formats

Datetime values will be returned as regular JSON format and Unix timestamps, the timestamps are suffixed with _int.

Error handling

Whenever an error is encountered, the answer to a JSON API call will have:

An HTTP 422 status (Unprocessable entity) or HTTP 400 (Bad request)
A JSON array of localized error messages in the errors attribute of the response body

Example:

{
  "errors": [
    "Operations account operations amount is greater than your available balance (1781.96 EUR)"
    "Amount can't be greater than your limit (1781.96 EUR)"
  ]
}

Successful calls

If the API call was successful, the platform will answer with:

An HTTP 200 status (OK) or HTTP 201 (Created),
A JSON representation of the entity being created or updated if relevant

Rate-limiting

API calls are rate-limited by IP to 86400 calls per day (one per second on average). Information about the status of the limit can be found in the X-RateLimit-Limit and X-RateLimit-Remaining HTTP headers.

Example response with rate-limit headers

HTTP/1.1 200  
Content-Type: application/json; charset=utf-8
X-Ratelimit-Limit: 5000
X-Ratelimit-Remaining: 4982
Date: Wed, 30 Jan 2013 12:08:58 GMT

Authentication

Permissions

Before you request authorization to access a user's account, you must decide which permissions, or scopes you would like to access.

The following scopes are available:

name	description
basic	Read account number, language, and balances (default)
activity	Read trade orders, deposits, withdrawals, and other operations
trade	Create and cancel trade orders
withdraw	Request EUR and BTC withdrawals (requires email confirmation from users upon withdrawing)
deposit	List bitcoin deposit addresses and create a new one if needed
merchant	Create and manage an account's invoices

Token authentication

This authentication mechanism is the recommended method if you need to access your own account data and is also referred to as HMAC authentication, if you need to access other users accounts on their behalf you'll need to use the OAuth2 authentication method.

Generating a token

For this authentication method you need to generate a token/secret pair that you will use to make requests against our API. In order to do so visit the "API tokens" menu in your account profile and click on "Create token". You will be presented with the following screen that will enable you to select the desired access permissions for this token. For security reasons you will need to confirm your access credentials.

Once your token is created you'll be presented once with the matching secret key, this secret key is only displayed once, you need to record it carefully. If the secret key is lost the token becomes useless.

Making requests

Once you have an API token and its matching secret key you can use them to make requests against our API. In order to do so you must include three HTTP headers that will authenticate your request.

$ curl "https://paymium.com/api/v1/user"               \
     --header "Api-Key: <YOUR API TOKEN>"              \
     --header "Api-Signature: <THE REQUEST SIGNATURE>" \
     --header "Api-Nonce: <AN UPDATED NONCE>"          \

The API key is the token that is displayed when listing your currently active tokens,
The API signature is the hexdigest of the HMAC-SHA256 hash of the nonce concatenated with the full URL and body of the HTTP request, encoded using your API secret key,
The nonce is a positive integer number that must increase with every request you make

OAuth2 authentication

This authentication mechanism is best suited to cases where a developer publishes an app that requires access its users Paymium accounts.

Many programming languages already have libraries to develop clients that connect to OAuth2 APIs, hence the following steps may not be necessary. For instance, if you are a Ruby developer, you can use this example to get started.

The process can be summarized as follows:

Send the user to your application's authorization URL
Receive the authorization code if the user accepted the request
Get an access token and a refresh token from the authorization code
Refresh the access token when needed

Requesting user authorization

To get user's permission to use his/her account, you must send him/her to your application's redirect URI. You can see this URI by visiting your application's page: https://paymium.com/page/developers/apps.

By default, the basic scope will be requested.

If your application requires specific access scopes, you must append a scope GET parameter to the authorization URI:

https://paymium.com/...&scope=basic+activity+trade

The user will then be prompted to authorize your application with the specified scopes.

Receiving the authorization code

If you specified the test redirection URI https://paymium.com/page/oauth/test, the user will be presented the autorization code upon accepting your request which can be used by the application to fetch access tokens.

Otherwise the code or error will be sent to the redirection URI so that your application can retrieve it (in this case https://example.com/callback):

https://example.com/callback?code=AUTHORIZATION_CODE

Or if the request was denied by the user:

https://example.com/callback?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.

The authorization code is valid 5 minutes.

Fetching an access token and a refresh token

Once your application received the authorization code, it can request an access token and a refresh token:

$ curl "https://paymium.com/api/oauth/token"                    \
    -d "client_id=APPLICATION_KEY"                              \
    -d "client_secret=APPLICATION_SECRET"                       \
    -d "grant_type=authorization_code"                          \
    -d "redirect_uri=REDIRECT_URI"                              \
    -d "code=AUTHORIZATION_CODE"

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 1800,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "basic"
}

An access token can be used to authorize user requests for the approved scopes and is valid 30 minutes.

Refreshing the access token

Since an access token is only valid 30 minutes, your application may need to fetch a new access token using the refresh token:

$ curl "https://paymium.com/api/oauth/token"                    \
    -d "client_id=APPLICATION_KEY"                              \
    -d "client_secret=APPLICATION_SECRET"                       \
    -d "grant_type=refresh_token"                               \
    -d "redirect_uri=REDIRECT_URI"                              \
    -d "refresh_token=REFRESH_TOKEN"

{
  "access_token": "NEW_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 1800,
  "refresh_token": "NEW_REFRESH_TOKEN",
  "scope": "basic"
}

After refreshing the access token, the previous tokens (access and refresh) are no longer valid.

Public data

Public data (ticker, asks, bids, trades) can be accessed without registering an application.

Countries

Description

Read the list of countries, we currently serve the residents of countries for which the accepted flag is set to true.

Endpoint

method	path	authorization
GET	/api/v1/countries	not required

Example

$ curl https://paymium.com/api/v1/countries

[
  {
    "id": 76,
    "accepted": true,
    "iso_alpha2": "FR",
    "iso_alpha3": "FRA",
    "iso_numeric": 250,
    "name_en": "France",
    "name_fr": "France",
    "telephone_code": 33
  },
  {
    "id": 157,
    "accepted": true,
    "iso_alpha2": "NL",
    "iso_alpha3": "NLD",
    "iso_numeric": 528,
    "name_en": "Netherlands",
    "name_fr": "Pays-Bas",
    "telephone_code": 31
  }
]

Ticker

Description

Read the latest ticker data.

Endpoint

method	path	authorization
GET	/api/v1/data/eur/ticker	not required

Example

$ curl https://paymium.com/api/v1/data/eur/ticker

{
  "high": 720.0,
  "low": 640.0001,
  "volume": 198.16844745,
  "bid": 676.01,
  "ask": 679.9999999,
  "midpoint": 678.00499995,
  "at": 1389092410,
  "price": 680.0,
  "vwap": 679.87459,
  "variation": -5.5556,
  "currency": "EUR"
}

Properties

name	description	example value
currency	currency	"EUR"
at	timestamp	1389092410
price	price of latest trade	680.0
bid	bid price	676.01
ask	ask price	679.9999999
midpoint	midpoint price	678.00499995
volume	24h volume	198.16844745
variation	24h variation (percentage)	-5.5556
high	24h high price	720.0
low	24h low price	640.0001
vwap	24h volume-weighted average price	679.87459

Latest trades

Description

Read the latest executed trades.

Endpoint

method	path	authorization
GET	/api/v1/data/eur/trades	not required

Parameters

name	description	required	type	default	example
since	The timestamp of the oldest trade to fetch.	false	Integer	1 week ago	`1389094259`

Example

$ curl "https://paymium.com/api/v1/data/eur/trades?since=1389094259"

[
  {
    "uuid": "59f9c458-cb22-48d6-9103-0b6e54130e29",
    "traded_btc": 0.153,
    "traded_currency": 102.51,
    "created_at": "2014-01-07T11:30:59Z",
    "currency": "EUR",
    "price": 670.0,
    "created_at_int": 1389094259
  },
  {
    "uuid": "4787c80b-bc90-48d4-87ee-b23fbff2fbb7",
    "traded_btc": 0.06,
    "traded_currency": 40.2,
    "created_at": "2014-01-07T11:31:00Z",
    "currency": "EUR",
    "price": 670.0,
    "created_at_int": 1389094260
  },
  {
    "uuid": "67838a4d-cd2e-47d1-9b3c-0ff7a6d2ea89",
    "traded_btc": 0.4,
    "traded_currency": 268.0,
    "created_at": "2014-01-07T11:31:00Z",
    "currency": "EUR",
    "price": 670.0,
    "created_at_int": 1389094260
  }
]

Properties

The response is an array of trades.

Trade properties

name	description	example value
uuid	unique ID of trade	"59f9c458-cb22-48d6-9103-0b6e54130e29"
currency	currency	"EUR"
created_at	date created	"2014-01-07T11:30:59Z"
created_at_int	timestamp	1389094259
price	price per BTC	670.0
traded_btc	amount of BTC traded	0.153
traded_currency	amount of currency traded	102.51

Market depth

Description

Read the market depth. Bids and asks are grouped by price.

Endpoint

method	path	authorization
GET	/api/v1/data/eur/depth	not required

Example

$ curl "https://paymium.com/api/v1/data/eur/depth"

{
  "bids": [
    {
      "timestamp": 1389087724,
      "amount": 0.89744,
      "price": 665.0,
      "currency": "EUR"
    },
    {
      "timestamp": 1389082088,
      "amount": 0.06,
      "price": 666.0,
      "currency": "EUR"
    }
  ],
  "asks": [
    {
      "timestamp": 1389094178,
      "amount": 0.57709999,
      "price": 679.99,
      "currency": "EUR"
    },
    {
      "timestamp": 1389092448,
      "amount": 0.20684181,
      "price": 680.0,
      "currency": "EUR"
    }
  ]
}

Properties

name	description
bids	an array of bids
asks	an array of asks

Bids / asks properties

name	description	example value
currency	currency	"EUR"
timestamp	timestamp	1389087724
price	price	665.0
amount	amount at price	0.06

Bitcoin-Charts endpoints

Two API endpoints dedicated to Bitcoin-Charts are publicly accessible, they are accessible at:

https://paymium.com/api/v1/bitcoin_charts/eur/trades, and
https://paymium.com/api/v1/bitcoin_charts/eur/depth

The data they return is formatted according to the Bitcoin Charts exchange API specification.

WebSocket

A socket.io endpoint is available to receive public data. This allows you to receive new data without having to poll the server.

The socket.io socket will emit a stream event when new data is available. The received JSON data contains one or more of the properties listed below, depending on what was updated.

Socket.io configuration

Socket.io must connect to paymium.com/<public or user> and the path option must be set to /ws/socket.io.

Message descriptions

The Websocket messages are documented separately: documentation.

Node.js example

Assuming you have node.js installed, you can install the socket.io client library by running npm install socket.io-client.

The code below shows how to connect to the Paymium socket, and outputs any received data to the console.

The example is available in the examples/public_socket.js directory of this repository.

var io = require('socket.io-client');

var socket = io.connect('paymium.com/public', {
  path: '/ws/socket.io'
});

console.log('CONNECTING');

socket.on('connect', function() {
  console.log('CONNECTED');
  console.log('WAITING FOR DATA...');
});

socket.on('disconnect', function() {
  console.log('DISCONNECTED');
});

socket.on('stream', function(data) {
  console.log('GOT DATA:');
  console.log(data);
});

FIX streaming API

The FIX API is documented separately: documentation.

User data

Before you can access your own data or other users data, you must register an application on Paymium:

Verify your account and log in
Visit https://paymium.com/page/developers/apps
Create an application (set redirect URI to https://paymium.com/page/oauth/test when testing)

User info

Description

Read the latest user info.

Endpoint

method	path	authorization
GET	/api/v1/user	oauth2 (scope: basic)

Example

$ curl "https://paymium.com/api/v1/user"                        \
     --header "Authorization: Bearer ACCESS_TOKEN"

{
  "name": "BC-U123456",
  "locale": "en",
  "balance_btc": 25.78866278,
  "locked_btc": 1.0,
  "balance_eur": 1893.96,
  "locked_eur": 300.00743886
}

Properties

name	description	example value
name	account number / name	"BC-U123456"
locale	locale code	"en"
balance_eur	available EUR balance	1893.96
locked_eur	EUR balance locked in trading	300.00743886
balance_btc	available BTC balance	25.78866278
locked_btc	BTC balance locked in trading	1.0

User activity

Description

Read user activity.

Endpoint

method	path	authorization
GET	/api/v1/user/orders	oauth2 (scope: activity)

Parameters

name	description	example value
offset	pagination offset (optional)	20
limit	pagination limit (optional)	20
types[]	filter by types (optional)	LimitOrder
active	only show active orders (optional)	true

Example

$ curl "https://paymium.com/api/v1/user/orders?offset=20"                \
     --header "Authorization: Bearer ACCESS_TOKEN"

[
  {
    "uuid": "968f4580-e26c-4ad8-8bcd-874d23d55296",
    "amount": 1.0,
    "state": "executed",
    "btc_fee": 0.0,
    "currency_fee": 0.0,
    "updated_at": "2013-10-24T10:34:37.000Z",
    "created_at": "2013-10-22T19:12:02.000Z",
    "currency": "BTC",
    "type": "Transfer",
    "account_operations": [
      {
        "uuid": "94b42d0f-9c2d-43f3-978b-aba28533d1f9",
        "name": "bitcoin_transfer",
        "amount": -1.0,
        "currency": "BTC",
        "created_at": "2013-10-22T19:12:02.000Z",
        "created_at_int": 1382469122,
        "is_trading_account": false
      }
    ]
  },
  {
    "uuid": "1953cd1b-3903-4812-9590-42c3ebcc08c2",
    "amount": 49.38727114,
    "state": "executed",
    "btc_fee": 0.0,
    "currency_fee": 0.0,
    "updated_at": "2013-10-22T14:30:06.000Z",
    "created_at": "2013-10-22T14:30:06.000Z",
    "currency": "BTC",
    "type": "AdminOrder",
    "account_operations": [
      {
        "uuid": "a940393b-4d2f-4a5a-8a0a-3470d7419bad",
        "name": "account_operation",
        "amount": 49.38727114,
        "currency": "BTC",
        "created_at": "2013-10-22T14:30:06.000Z",
        "created_at_int": 1382452206,
        "is_trading_account": false
      }
    ]
  }
]

Properties

The response is an array of orders. See order properties.

Order details

Description

Read details from a specific order.

Endpoint

method	path	authorization
GET	/api/v1/user/orders/{UUID}	oauth2 (scope: activity)

Example

$ curl "https://paymium.com/api/v1/user/orders/968f4580-e26c-4ad8-8bcd-874d23d55296"         \
     --header "Authorization: Bearer ACCESS_TOKEN"

{
  "uuid": "968f4580-e26c-4ad8-8bcd-874d23d55296",
  "amount": 1.0,
  "state": "executed",
  "btc_fee": 0.0,
  "currency_fee": 0.0,
  "updated_at": "2013-10-24T10:34:37.000Z",
  "created_at": "2013-10-22T19:12:02.000Z",
  "currency": "BTC",
  "type": "Transfer",
  "account_operations": [
    {
      "uuid": "94b42d0f-9c2d-43f3-978b-aba28533d1f9",
      "name": "bitcoin_transfer",
      "amount": -1.0,
      "currency": "BTC",
      "created_at": "2013-10-22T19:12:02.000Z",
      "created_at_int": 1382469122,
      "is_trading_account": false
    }
  ]
}

Properties

See order properties.

Trading

Description

Create trade orders.

Limit and market orders are supported, the price parameter must be omitted for market orders.

Either one of amount or currency_amount must be specified. When the amount is specified, the engine will buy or sell this amount of Bitcoins. When the currency_amount is specified, the engine will buy as much Bitcoins as possible for currency_amount or sell as much Bitcoins as necessary to obtain currency_amount.

Endpoint

method	path	authorization
POST	/api/v1/user/orders	oauth2 (scope: trade)

Payload

name	description	example value
type	must be "LimitOrder" or "MarketOrder"	"LimitOrder"
currency	must be "EUR"	"EUR"
direction	trade direction, must be "buy" or "sell"	"buy"
price	price per BTC, must be omitted for market orders	300.0
amount	BTC amount to trade (only if no currency_amount is specified)	1.0
currency_amount	Currency amount to trade (only if no amount is specified)	1.0

Example

$ curl "https://paymium.com/api/v1/user/orders"                     \
     --header "Authorization: Bearer ACCESS_TOKEN"                  \
     -d "type=LimitOrder"                                           \
     -d "currency=EUR"                                              \
     -d "direction=buy"                                             \
     -d "price=300.0"                                               \
     -d "amount=1.0"

Would return:

{
  "uuid": "4924ee0f-f60e-40b4-b63e-61637ef253ac",
  "amount": 1.0,
  "state": "pending_execution",
  "btc_fee": 0.0,
  "currency_fee": 0.0,
  "updated_at": "2013-11-21T15:27:04.000Z",
  "created_at": "2013-11-21T15:27:04.000Z",
  "currency": "EUR",
  "type": "LimitOrder",
  "traded_btc": 0.0,
  "traded_currency": 0.0,
  "direction": "buy",
  "price": 300.0,
  "account_operations": [
    {
      "uuid": "63e1d9c4-dff2-42bc-910b-c5b585b625cc",
      "name": "lock",
      "amount": -300.0,
      "currency": "EUR",
      "created_at": "2013-11-21T15:27:04.000Z",
      "created_at_int": 1385047624,
      "is_trading_account": false
    },
    {
      "uuid": "c9d3e824-b29a-4630-8396-3864a0704336",
      "name": "lock",
      "amount": 300.0,
      "currency": "EUR",
      "created_at": "2013-11-21T15:27:04.000Z",
      "created_at_int": 1385047624,
      "is_trading_account": true
    }
  ]
}

Properties

See order properties.

Withdrawing

Request BTC or fiat withdrawals. A confirmation is sent by email to the user before it can be executed.

Endpoint

method	path	authorization
POST	/api/v1/user/orders	oauth2 (scope: withdraw)

Payload

name	description	example value
type	must be "Transfer"	"Transfer"
currency	currency code	"BTC"
amount	amount to transfer	0.5
address	BTC address if withdrawing BTC	"1PzU1ERAnHJmtU8J3qq3wwJhyLepwUYzHn"

Example

$ curl "https://paymium.com/api/v1/user/orders"                     \
     --header "Authorization: Bearer ACCESS_TOKEN"                  \
     -d "type=Transfer"                                             \
     -d "currency=BTC"                                              \
     -d "amount=0.5"                                                \
     -d "address=1PzU1ERAnHJmtU8J3qq3wwJhyLepwUYzHn"

Would return:

{
  "uuid": "9229fd6e-0aad-45d6-8090-a400f37a0129",
  "amount": 0.5,
  "state": "pending",
  "btc_fee": 0.0,
  "currency_fee": 0.0,
  "updated_at": "2014-01-09T10:22:00.858Z",
  "created_at": "2014-01-09T10:22:00.858Z",
  "currency": "BTC",
  "type": "Transfer",
  "account_operations": [
    {
      "uuid": "4c4f4682-354f-46d1-a916-72d88d5584e3",
      "name": "bitcoin_transfer",
      "amount": -0.5,
      "currency": "BTC",
      "created_at": "2014-01-09T10:22:02.171Z",
      "created_at_int": 1389262922,
      "is_trading_account": false
    }
  ]
}

Properties

See order properties.

Sending money

Description

Initiate a money transfer to an e-mail address.

The transfer is immediately executed if the user have a valid account. Otherwise, an e-mail is sent with a registration invitation.

This transfer expire after 1 month if it is not collected. In this case, the order is cancelled and the sender re-credited.

Endpoint

method	path	authorization
POST	/api/v1/user/orders	oauth2 (scope: send)

Payload

name	description	example value
type	must be "EmailTransfer"	"EmailTransfer"
currency	currency code	"BTC"
amount	amount to transfer	0.5
email	an e-mail address	"user@example.com"
comment	a small note explaining the transfer	"Hi, refund for that thing"

Example

$ curl "https://paymium.com/api/v1/user/orders"                     \
     --header "Authorization: Bearer ACCESS_TOKEN"                  \
     -d "type=EmailTransfer"                                        \
     -d "currency=BTC"                                              \
     -d "amount=0.5"                                                \
     -d "email=user@example.com"                                    \
     -d "comment=Hi, refund for that thing"

Would return:

{
  "uuid": "9229fd6e-0aad-45d6-8090-a400f37a0129",
  "amount": 0.5,
  "state": "pending",
  "btc_fee": 0.0,
  "currency_fee": 0.0,
  "updated_at": "2014-01-09T10:22:00.858Z",
  "created_at": "2014-01-09T10:22:00.858Z",
  "currency": "BTC",
  "type": "EmailTransfer",
  "account_operations": [
    {
      "uuid": "4c4f4682-354f-46d1-a916-72d88d5584e3",
      "name": "email_transfer",
      "amount": -0.5,
      "currency": "BTC",
      "created_at": "2014-01-09T10:22:02.171Z",
      "created_at_int": 1389262922,
      "is_trading_account": false
    }
  ]
}

Requesting money by e-mail

Description

This functionality allows one to create a payment request that is sent by e-mail to the designated recipient, when the link contained in the e-mail is clicked, the recipient is presented with a Bitcoin address to which he is instructed to direct his payment.

Once the Bitcoin payment is confirmed, the payee is credited in the originally requested currency.

Endpoint

method	path	authorization
POST	/api/v1/user/payment_requests	oauth2 (scope: receive)

Payload

name	description	example value
type	must be "PaymentRequest"	"PaymentRequest"
currency	currency code	"BTC"
amount	amount to transfer	0.5
email	an e-mail address	"user@example.com"
payment_split	Percentage of the payment the merchant will get in `currency` expressed as a two-decimal places float between 0 and 1 (required)	1.0
comment	a small note explaining the transfer	"Hi, refund for that thing"

Example

$ curl "https://paymium.com/api/v1/user/payment_requests" \
     --header "Authorization: Bearer ACCESS_TOKEN"        \
     -d "type=PaymentRequest"                             \
     -d "currency=BTC"                                    \
     -d "amount=0.5"                                      \
     -d "email=user@example.com"                          \
     -d "payment_split=1"                                 \
     -d "comment=Hi, refund for that thing"

If successful, responds with a HTTP/1.1 201 Created status code.

Canceling orders

Description

Cancel an order. Only active trade orders and email tranfers may be canceled.

Endpoint

method	path	authorization
DELETE	/api/v1/user/orders/{UUID}/cancel	oauth2 (scope: trading)

Example

$ curl "https://paymium.com/api/v1/user/orders/968f4580-e26c-4ad8-8bcd-874d23d55296"         \
     -X DELETE --header "Authorization: Bearer ACCESS_TOKEN"

Bitcoin addresses

Description

List and create bitcoin deposit addresses

Endpoint

method	path	authorization
GET	/api/v1/user/addresses	oauth2 (scope: deposit)
GET	/api/v1/user/addresses/:btc_address	oauth2 (scope: deposit)
POST	/api/v1/user/addresses	oauth2 (scope: deposit)

Examples

Retrieve your Bitcoin deposit addresses along with their expiration timestamp.

$ curl "https://paymium.com/api/v1/user/addresses"         \
     --header "Authorization: Bearer ACCESS_TOKEN"

[
  {
    "address": "1PzU1ERAnHJmtU8J3qq3wwJhyLepwUYzHn",
    "valid_until": 1402579836
  }
]

Retrieve details for a single address.

$ curl "https://paymium.com/api/v1/user/addresses/1PzU1ERAnHJmtU8J3qq3wwJhyLepwUYzHn"         \
     --header "Authorization: Bearer ACCESS_TOKEN"

{
  "address": "1PzU1ERAnHJmtU8J3qq3wwJhyLepwUYzHn",
  "valid_until": 1402579836
}

Create a new Bitcoin deposit address unless another one is already active.

$ curl -X POST "https://bitcoin-central.net/api/v1/user/addresses" \
     --header "Authorization: Bearer ACCESS_TOKEN"

{
  "address": "1PzU1ERAnHJmtU8J3qq3wwJhyLepwUYzHn",
  "valid_until": 1402579836
}

Price alerts

Description

Register a mobile device for alerts on price movements.

Endpoint

method	path	authorization
GET	/api/v1/user/price_alerts	oauth2 (scope: activity)
POST	/api/v1/user/price_alerts	oauth2 (scope: activity)
DELETE	/api/v1/user/price_alerts/:id	oauth2 (scope: activity)

Examples

Retrieve currently active price alerts.

$ curl "https://paymium.com/api/v1/user/price_alerts" \
     --header "Authorization: Bearer ACCESS_TOKEN"

[
  {
    "id": 42,
    "token": "0ff2f39d-cd9f-4710-9eb5-3f8385f5e059",
    "notify_above": 220.5,
    "notify_below": 180.0,
    "last_sent_at": 1445610041
  }
]

Create a new price alert.

$ curl "https://paymium.com/api/v1/user/price_alerts"     \
     -X POST                                              \
     --header "Authorization: Bearer ACCESS_TOKEN"        \
     -d "token=0ff2f39d-cd9f-4710-9eb5-3f8385f5e059"      \
     -d "notify_below=100"                                \
     -d "notify_above=110"                                \

If successful, it responds with a HTTP/1.1 201 Created status code.

Merchant API

The Merchant API enables merchants to securely sell goods and services and get paid in Bitcoin. The API makes it possible for the merchant to completely eliminate the risk of market fluctuations when requesting to receive fiat currency in their account. It is also possible to keep a part of the payment in Bitcoin without having it converted at a guaranteed rate.

The API allows developers to integrate Bitcoin payments very tightly into their platforms, pre-packaged plugins are also available for a growing list of popular e-commerce frameworks.

For merchants that have very simple needs payment buttons are also available, these buttons remove the integration completely by allowing merchants to simply include a code snippet on a static HTML page, or on a blog to receive fixed-amount payments.

Payment creation

Authentication

The "merchant token" authentication mechanism has been removed please use an API token or an OAuth2 token instead with the "merchant" scope.

Description

A payment is created by a merchant platform when the customer chooses Bitcoin as his desired checkout option.

The merchant platform can then :

display the payment Bitcoin address on his own web interface,
include the Paymium web interface url in an iframe in order to display a payment pop-up as an overlay,
redirect the buyer to the payement's URL (see below), in this case the payment is displayed on a separate screen

To display the payment request to the user, the https://paymium.com/invoice/{UUID} can be used, this is used by the e-commerce framework plugins.

Once the payment request is displayed, the customer has 15 minutes to send the appropriate amount.

Paymium notifies the merchant of the completion of his payment via the associated callback (for which an URL may be provided when creating the payment request), once one Bitcoin confirmation for the payment is received the funds are credited to the merchant's account, a callback notification is then made.

Endpoint

method	path	authorization
POST	/api/v1/merchant/create_payment	oauth2 (scope: merchant)

Parameters

name	description	example value
amount	Amount requested for the payment (required)	20
payment_split	Percentage of the payment the merchant will get in `currency` expressed as a two-decimal places float between 0 and 1 (required)	1.0
currency	Currency in which the merchant wishes to be credited and in which the `amount` is expressed (required)	EUR
callback_url	Merchant callback URL, it is called when the state of the payment changes (optional)	http://myonlineshop/payments/order-987978/callback
redirect_url	URL to which the customer should be redirected at upon payment (optional)	http://myonlineshop/payments/order-987978/success
merchant_reference	Arbitrary merchant data associated to the payment (optional)	order-987978

Response

See Payment properties

Payment callbacks

When a payment is created or updated, and if a callback URL was provided, a notification is made.

When the notification is made a POST request is made to the callback URL, it contains the JSON representation of the payment (see the payment properties).

The merchant should ensure the callback is legitimate by requesting confirmation from the Paymium API for the invoice data.

Note : The callback notifications are not guaranteed to be unique, it must have idempotent results on the merchant side if the payment has not actually changed.

Get payment information

This endpoint returns the payment request as a JSON object given a payment UUID

Endpoint

Method	Path
GET	/api/v1/merchant/get_payment/{UUID}

Returned JSON object properties

Name	Description
uuid	Payment UUID
currency	Currency in which the `currency_amount` is expressed
payment_split	Percentage of the payment the merchant will get in `currency`
state	See payment states
callback_url	Merchant notification URL
redirect_url	Redirection url to which the customer is redirected on success
merchant_name	Name of the merchant that is displayed to the customer
expires_at	Expiration timestamp
merchant_reference	Reference string associated to the payment
amount	Amount associated to the payment
btc_amount	BTC amount to pay
payment_address	Payment address
created_at	Creation timestamp
updated_at	Last update timestamp
account_operations	Account operations made against the merchant account

Example

{
    "account_operations": [
        {
            "amount": 25.0,
            "created_at": "2014-05-15T10:19:21.000Z",
            "created_at_int": 1400149161,
            "currency": "EUR",
            "is_trading_account": false,
            "name": "merchant_currency_payment",
            "uuid": "afca953b-dfa6-40b6-b856-c04d548baefb"
        }
    ],
    "amount": 25.0,
    "btc_amount": 0.079945,
    "callback_url": "http://mysite.com/wc-api/WC_Paymium/",
    "cancel_url": "http://mysite.com/commande/panier/",
    "comment": null,
    "created_at": 1400147834,
    "currency": "EUR",
    "expires_at": 1400148734,
    "merchant_name": "Demo SAS",
    "merchant_reference": "888",
    "payment_address": "1NHRnMn1831D84owh7powxtAbqfzA9aaL5",
    "payment_split": 1.0,
    "redirect_url": "http://mysite.com/order/checkout/order-received/888?key=wc_order_53784&order=888",
    "state": "paid",
    "updated_at": 1400149161,
    "uuid": "f8e7c539-7b7b-4b63-9ccf-5fc2ca91bf0b"
}

E-commerce frameworks plugins

The currently available plugins are available

Framework	Plugin URL
PrestaShop 1.6	https://github.com/Paymium/prestashop
WooCommerce	https://github.com/Paymium/woocommerce

Appendix

Currencies

The following currencies are available:

symbol	currency
EUR	Euro
BTC	Bitcoin

Order types

Orders can have the following types:

type	description
WireDeposit	wire (fiat) deposit
BitcoinDeposit	BTC deposit
LimitOrder	limit trade order
Transfer	BTC or fiat transfer or withdraw
EmailTransfer	BTC or fiat transfer by e-mail
AdminOrder	special order executed by an admin

Order properties

All order types share generic properties.

Each type may have additional properties as described below.

Generic order properties

name	description	example value
uuid	unique id	"968f4580-e26c-4ad8-8bcd-874d23d55296"
type	order type	"Transfer"
currency	currency	"BTC"
created_at	date created	"2013-10-24T10:34:37.000Z"
updated_at	date updated	"2013-10-22T19:12:02.000Z"
amount	currency amount	1.0
state	order state	"executed"
currency_fee	currency fee collected	0.0
btc_fee	BTC fee collected	0.0
comment	optional comment
account_operations	an array of account operations executed

Market order specific properties

name	description	example value
direction	trade direction ("buy" or "sell")	"buy"
price	price per BTC	620.0
traded_currency	currency exchanged	310.0
traded_btc	BTC echanged	0.5

EmailTransfer specific properties

name	description	example value
email_address	email address of the receiver	"user@example.com"

Order states

name	description
pending_execution	order is queued and pending execution
pending	order is pending, such as an unconfirmed withdrawal
processing	order is processing
authorized	order has been authorized, such as a confirmed withdrawal
active	order is active, such as a trade order in the order book
filled	order has been completely filled
executed	order has been executed
canceled	order has been canceled

Email Transfer states

Name	Description
pending	Email Transfer is pending the email confirmation
pending_collection	Email Transfer queued and pending for the receiver registration and profile completion
executed	Email Transfer has been executed
expired	Email Transfer has expired
canceled	Email Transfer has been canceled

Payment states

Name	Description
pending_payment	Waiting for payment
processing	The correct amount has been received, waiting for a Bitcoin network confirmation
paid	Payment completed, the requested amount has been credited to the merchant account
error	An error has occurred, the merchant must get in touch with the support
btc_forwarded	Due to an incorrect paid, the received funds could not be converted and have been credited directly to the merchant
expired	Payment expired, no Bitcoins were received

Account operation properties

name	description	example value
uuid	unique id	"a940393b-4d2f-4a5a-8a0a-3470d7419bad"
currency	currency	"BTC"
name	name of operation	"account_operation"
created_at	date created	"2013-10-22T14:30:06.000Z"
created_at_int	timestamp	1382452206
amount	currency amount	49.38727114
address	bitcoin address if any	"1FPDBXNqSkZMsw1kSkkajcj8berxDQkUoc"
tx_hash	bitcoin transaction hash if any	"86e6e72aa559428524e035cd6b2997004..."
is_trading_account	whether the trading account is targeted	false

Ruby example

This example uses the OAuth2 Ruby gem.

The AutoRefreshToken class encapsulates this logic, it is available as a Gist.

require 'oauth2'

client = OAuth2::Client.new('6fcf1c32f6e14cd773a7a6640832bdbf83a5b2b8d4382e839c6aff83a8f1bb3b', '55554ecad5627f0465034c4a116e59a38d9c3ab272487a18404078ccc0b64798', site: 'https://paymium.com', authorize_url: '/api/oauth/authorize', token_url: '/api/oauth/token')

client.auth_code.authorize_url(redirect_uri: 'https://paymium.com/page/oauth/test', scope: 'basic activity trade withdraw')
 => "https://staging.paymium.com/api/oauth/authorize?response_type=code&client_id=71a28131e16a0d6756a41aa391f1aa28b2f5a2ed4a6b911cf2bf640c8a0cc2cd&redirect_uri=https%3A%2F%2Fstaging.paymium.com%2Fpage%2Foauth%2Ftest&scope=basic+activity+trade+withdraw"

# Visit this URL in your browser, approve the request and copy the authorization code

authorization_code = '9b55e27c840f59d927284fdc438ee3d8fac94b00e24d331162ddff76c1a6bcc0'

token = client.auth_code.get_token(authorization_code, redirect_uri: 'https://paymium.com/page/oauth/test')

token.get('/api/v1/user').body
=> {"name":"BC-U123456","locale":"en","balance_btc":117.56672217,"locked_btc":0.0,"balance_eur":0.0,"locked_eur":0.00995186}

Name		Name	Last commit message	Last commit date
Latest commit History 135 Commits
contrib		contrib
examples		examples
README.md		README.md
WEBSOCKETS.md		WEBSOCKETS.md
create-api-token.png		create-api-token.png
display-invoice.png		display-invoice.png
logo.png		logo.png

Paymium/old-api-documentation

Folders and files

Latest commit

History

Repository files navigation

Table of contents

General information

Formats and required HTTP request headers

Localization

Datetime formats

Error handling

Example:

Successful calls

Rate-limiting

Authentication

Permissions

Token authentication

Generating a token

Making requests

OAuth2 authentication

Requesting user authorization

Receiving the authorization code

Fetching an access token and a refresh token

Refreshing the access token

Public data

Countries

Description

Endpoint

Example

Ticker

Description

Endpoint

Example

Properties

Latest trades

Description

Endpoint

Parameters

Example

Properties

Trade properties

Market depth

Description

Endpoint

Example

Properties

Bids / asks properties

Bitcoin-Charts endpoints

WebSocket

Socket.io configuration

Message descriptions

Node.js example

FIX streaming API

User data

User info

Description

Endpoint

Example

Properties

User activity

Description

Endpoint

Parameters

Example

Properties

Order details

Description

Endpoint

Example

Properties

Trading

Description

Endpoint

Payload

Example

Properties

Withdrawing

Endpoint

Payload

Example

Packages