Paymium API (1.1.1)

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

It 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.

The official changelog is currently on GitHub. You can be notified of the latest changes by watching our official documentation repository.

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.

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

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

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)"
    ]
  }

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

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

Examples in the documentation are using the ccxt library, which supports Paymium's API and is available for Python, JavaScript and PHP.

Installation instructions can be found on GitHub.

Public data (ticker, asks, bids, trades) can be accessed without authentication.

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.

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.

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 must connect to https://paymium.com/<public or user> and the path option must be set to /ws/socket.io.

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.

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

  var socket = io.connect('https://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);
  });

Websockets are implemented using socket.io v1.3.

You must connect your socket.io client to paymium.com/public, setting the path option to /ws/socket.io. When new data is available, a stream event is triggered.

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

  var socket = io.connect('https://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(publicData) {
  console.log('GOT DATA:');
  console.log(publicData);
  });

The stream event will emit an object when new data is available. The object will have properties only for the data that changed.

publicData.ticker

If the ticker changed, publicData.ticker will contains the new ticker information. Example:

  {
  ticker: {
    high: "275",
    low: "275",
    volume: "0.10909089",
    bid: "205",
    ask: "275",
    midpoint: "240",
    vwap: "275",
    at: 1446464202,
    price: "275",
    open: "270",
    variation: "1.8519",
    currency: 'EUR',
    trade_id: '460aff60-8fff-4fb0-8be5-2f8dc67758c2'
    }
  }

publicData.trades

If new trades are executed, publicData.trades will be an array containing the new trades. Example:

  {
      trades: [
          {
          price: "275",
          traded_btc: "0.03636363",
          timestamp: 1446464202000,
          currency: 'EUR'
          }
      ]
  }

publicData.bids

If buy orders have changed (created, changed, or deleted), publicData.bids will be an array containing the modified orders. Orders are aggregated by price. If amount is 0, there are no more orders at this price. Example:

  {
      bids: [
          {
              timestamp: 1424208720,
              amount: "17.43992373",
              price: "265",
              currency: 'EUR'
          }
      ]
  }

publicData.asks

If sell orders have changed (created, changed, or deleted), publicData.asks will be an array containing the modified orders. Orders are aggregated by price. If amount is 0, there are no more orders at this price. Example:

  {
      asks: [
          {
              timestamp: 1424208720,
              amount: 17.43992373,
              price: 275,
              currency: 'EUR'
          }
      ]
  }

You must connect your socket.io client to https://paymium.com/user, setting the path option to /ws/socket.io. You must emit a channel event with the user channel id. This channel id is available in the user's json (/api/v1/user). When new data is available, a stream event is triggered.

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

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

  console.log('CONNECTING');

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

  // Replace USER_CHANNEL_ID with the channel id of the user
  socket.emit('channel', 'USER_CHANNEL_ID');

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

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

The stream event will emit an object when new data is available. The object will have properties only for the data that changed.

userData.balance_eur

If the available EUR balance changed, userData.balance_eur will contain the new balance.

  {
      balance_eur: "410.04"
  }

userData.locked_eur

If the locked EUR balance changed, userData.locked_eur will contain the new balance.

  {
      locked_eur: "20.24"
  }

userData.balance_btc

If the available BTC balance changed, userData.balance_btc will contain the new balance.

  {
      balance_btc: "53.29811458"
  }

userData.locked_btc

If the locked BTC balance changed, userData.locked_btc will contain the new balance.

  {
      locked_btc: "0"
  }

userData.orders

If user orders have changed (created, filled, cancelled, etc...), userData.orders will be an array containing the modified orders. You can check the state of the orders to handle them properly. Example:

  {
      orders: [
          {
              uuid: '89d4b612-5e6a-4154-94f3-120d03f4e891',
              amount: "1",
              currency_amount: "10",
              state: "pending_execution",
              btc_fee: "0",
              currency_fee: "0",
              updated_at: '2015-11-02T11:36:41.000Z',
              created_at: '2015-11-02T11:36:41.000Z',
              currency: 'EUR',
              comment: null,
              type: 'MarketOrder',
              traded_btc: "0",
              traded_currency: "0",
              direction: 'buy',
              price: "1000",
              account_operations: []
          }
      ]
  }