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
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
errorsattribute of the response body
{
"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
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 |
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.
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.
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
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
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.
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.
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.
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 (ticker, asks, bids, trades) can be accessed without registering an application.
Read the list of countries, we currently serve the residents of countries for which the accepted flag is set to true.
| method | path | authorization |
|---|---|---|
| GET | /api/v1/countries | not required |
$ 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
}
]Read the latest ticker data.
| method | path | authorization |
|---|---|---|
| GET | /api/v1/data/eur/ticker | not required |
$ 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"
}| 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 |
Read the latest executed trades.
| method | path | authorization |
|---|---|---|
| GET | /api/v1/data/eur/trades | not required |
| name | description | required | type | default | example |
|---|---|---|---|---|---|
| since | The timestamp of the oldest trade to fetch. | false | Integer | 1 week ago | 1389094259 |
$ 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
}
]The response is an array of trades.
| 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 |
Read the market depth. Bids and asks are grouped by price.
| method | path | authorization |
|---|---|---|
| GET | /api/v1/data/eur/depth | not required |
$ 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"
}
]
}| name | description |
|---|---|
| bids | an array of bids |
| asks | an array of asks |
| name | description | example value |
|---|---|---|
| currency | currency | "EUR" |
| timestamp | timestamp | 1389087724 |
| price | price | 665.0 |
| amount | amount at price | 0.06 |
Two API endpoints dedicated to Bitcoin-Charts are publicly accessible, they are accessible at:
https://paymium.com/api/v1/bitcoin_charts/eur/trades, andhttps://paymium.com/api/v1/bitcoin_charts/eur/depth
The data they return is formatted according to the Bitcoin Charts exchange API specification.
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 paymium.com/<public or user> and the path option must be set to /ws/socket.io.
The Websocket messages are documented separately: documentation.
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);
});The FIX API is documented separately: documentation.
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/testwhen testing)
Read the latest user info.
| method | path | authorization |
|---|---|---|
| GET | /api/v1/user | oauth2 (scope: basic) |
$ 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
}| 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 |
Read user activity.
| method | path | authorization |
|---|---|---|
| GET | /api/v1/user/orders | oauth2 (scope: activity) |
| 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 |
$ 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
}
]
}
]The response is an array of orders. See order properties.
Read details from a specific order.
| method | path | authorization |
|---|---|---|
| GET | /api/v1/user/orders/{UUID} | oauth2 (scope: activity) |
$ 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
}
]
}See order properties.
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.
| method | path | authorization |
|---|---|---|
| POST | /api/v1/user/orders | oauth2 (scope: trade) |
| 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 |
$ 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
}
]
}See order properties.
Request BTC or fiat withdrawals. A confirmation is sent by email to the user before it can be executed.
| method | path | authorization |
|---|---|---|
| POST | /api/v1/user/orders | oauth2 (scope: withdraw) |
| 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" |
$ 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
}
]
}See order properties.
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.
| method | path | authorization |
|---|---|---|
| POST | /api/v1/user/orders | oauth2 (scope: send) |
| name | description | example value |
|---|---|---|
| type | must be "EmailTransfer" | "EmailTransfer" |
| currency | currency code | "BTC" |
| amount | amount to transfer | 0.5 |
| an e-mail address | "user@example.com" | |
| comment | a small note explaining the transfer | "Hi, refund for that thing" |
$ 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
}
]
}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.
| method | path | authorization |
|---|---|---|
| POST | /api/v1/user/payment_requests | oauth2 (scope: receive) |
| name | description | example value |
|---|---|---|
| type | must be "PaymentRequest" | "PaymentRequest" |
| currency | currency code | "BTC" |
| amount | amount to transfer | 0.5 |
| 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" |
$ 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.
Cancel an order. Only active trade orders and email tranfers may be canceled.
| method | path | authorization |
|---|---|---|
| DELETE | /api/v1/user/orders/{UUID}/cancel | oauth2 (scope: trading) |
$ curl "https://paymium.com/api/v1/user/orders/968f4580-e26c-4ad8-8bcd-874d23d55296" \
-X DELETE --header "Authorization: Bearer ACCESS_TOKEN"List and create bitcoin deposit addresses
| 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) |
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
}Register a mobile device for alerts on price movements.
| 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) |
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.
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.
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.
| method | path | authorization |
|---|---|---|
| POST | /api/v1/merchant/create_payment | oauth2 (scope: merchant) |
| 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 |
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.
This endpoint returns the payment request as a JSON object given a payment UUID
| Method | Path |
|---|---|
| GET | /api/v1/merchant/get_payment/{UUID} |
| 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"
}The currently available plugins are available
| Framework | Plugin URL |
|---|---|
| PrestaShop 1.6 | https://github.com/Paymium/prestashop |
| WooCommerce | https://github.com/Paymium/woocommerce |
The following currencies are available:
| symbol | currency |
|---|---|
| EUR | Euro |
| BTC | Bitcoin |
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 |
All order types share generic properties.
Each type may have additional properties as described below.
| 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 |
| 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 |
| name | description | example value |
|---|---|---|
| email_address | email address of the receiver | "user@example.com" |
| 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 |
| 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 |
| 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 |
| 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 |
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}