NAV
ruby

Introduction

The base URL for production is https://pay.quoine.com/api/v1. All responses are in JSON format with the following status codes:

HTTP 200: OK
  Response is correct. The body of the response will
  include the data requested.

HTTP 400: Bad Request
  There was an error with the request. The body of the response will have more info

HTTP 401: Unauthorized
  Token is invalid. If your API key is wrong a 401 will also be served,
  so check the response body, it might be that the API_KEY is invalid.

HTTP 422: Unprocessable Entity
  There was an error with the request. The body of the response will have more info. Some possible reasons:
  - Missing params
  - The format of data is wrong

HTTP 503: Service Unavailable
  Many reasons, body will include details
  - An internal error on Authy.
  - Your application is accessing an API call you don't have access too.
  - API usage limit. If you reach API usage limits a 503 will be returned,
  please wait until you can do the call again.

Quoine Payment API provides a simple REST API that allows merchants to receive payments via bitcoin.

Note that with our Payment System, although buyers pay with bitcoin merchants always receive the payment in their exact quoted amount and currency, eliminating bitcoin’s volatility factor.

1. Authentication

By default, you need to pass authorized params (in Authentication) for all requests, otherwise, you will get HTTP status 401.

require 'uri'
require 'net/http'
require 'time'
require 'securerandom'
require 'base64'

uri = URI.parse("https://api.quoine.com")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

user_id = 'YOUR_USER_ID'
user_secret = 'YOUR_USER_SECRET'
path = "/profile"

nonce = SecureRandom.hex
date = Time.now.httpdate
canonical_string = "application/json,,#{path},#{date},#{nonce}"
signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha1'), user_secret, canonical_string))

request = Net::HTTP::Get.new(path)
request.add_field('Content-Type', 'application/json')
request.add_field('Date', date)
request.add_field('NONCE', nonce)
request.add_field('Authorization', "APIAuth #{user_id}:#{signature}")

response = http.request(request)

Once registered, users can access their User ID and User Secret in Settings page

You can manually authenticate using these headers or just use this ruby tool api_auth (quoine branch)

Request Headers:

Header Optional? Description
Content-Type content type, eg. “application/json”
Content-MD5 yes MD5 base 64 hash of the request content
Date timestamp in http date format, eg. “Sat, 27 Sep 2014 04:55:17 GMT”
NONCE random 32 chars alphanumeric string. Each request needs a different NONCE, eg. “0599e5ed6cbb522053f4faf4eccfbd3a”
Authorization “APIAuth user_id:signature”, eg. “APIAuth 1:tq63DFC2IFHLNQb1ACQDNl9kDkw=”

2. Create An Invoice

POST /invoices

Sample request

{
  "amount": 100,
  "name": "Invoice #70",
  "data": {
    "order_id": "192882",
    "items": []
  }
}

Request Parameters:

Sample response

{
  "id": 1,
  "invoice_status": "payment_awaited",
  "user_id": 2,
  "sub_account_id": 1,
  "bitcoin_address": "19wMMfLQ4Hu2XehHAbR3xY9UMEaaRLUMf4",
  "bitcoin_uri": "bitcoin:19wMMfLQ4Hu2XehHAbR3xY9UMEaaRLUMf4?amount=0.5",
  "name": "invoice name",
  "data": {
    "order_id": "192882",
    "items": []
  },
  "amount": "100.0",
  "bitcoin_amount": 0.5,
  "bitcoin_amount_received": 0,
  "currency": "USD",
  "qrcode_address_url": "http://chart.googleapis.com/chart?chs=500x500&cht=qr&chl=19wMMfLQ4Hu2XehHAbR3xY9UMEaaRLUMf4",
  "qrcode_protocol_url": "http://chart.googleapis.com/chart?chs=500x500&cht=qr&chl=bitcoin:19wMMfLQ4Hu2XehHAbR3xY9UMEaaRLUMf4?amount=0.5",
  "paid_at": null,
  "created_at": "2014-08-08T19:40:12.855+09:00",
  "updated_at": "2014-08-08T19:40:12.855+09:00",
  "expired_at": "2014-08-08T20:10:12.855+09:00"
}

Response Parameters:

3. Get An Invoice

GET /invoices/{id}

Parameters

Sample response

{
  "id": 1,
  "invoice_status": "payment_confirmed",
  "user_id": 1,
  "sub_account_id": 1,
  "bitcoin_address": "19wMMfLQ4Hu2XehHAbR3xY9UMEaaRLUMf4",
  "bitcoin_uri": "bitcoin:19wMMfLQ4Hu2XehHAbR3xY9UMEaaRLUMf4?amount=0.5",
  "name": "invoice name",
  "data": "any data",
  "amount": "500.0",
  "bitcoin_amount": 0.5,
  "bitcoin_amount_received": 0.5,
  "currency": "USD",
  "status": "btc_sent",
  "qrcode_address_url": "http://chart.googleapis.com/chart?chs=500x500&cht=qr&chl=19wMMfLQ4Hu2XehHAbR3xY9UMEaaRLUMf4",
  "qrcode_protocol_url": "http://chart.googleapis.com/chart?chs=500x500&cht=qr&chl=bitcoin:19wMMfLQ4Hu2XehHAbR3xY9UMEaaRLUMf4?amount=0.5",
  "paid_at": "2014-08-08T20:18:48.813+09:00",
  "created_at": "2014-08-08T20:08:48.813+09:00",
  "updated_at": "2014-08-08T20:08:48.813+09:00",
  "expired_at": "2014-08-08T20:38:48.813+09:00"
}

Sample error:

{
  "status": "fail",
  "message": "Invoice not found"
}

4. Get All Invoices

GET /invoices
GET /invoices?page=2&per=5

Parameters:

Sample response:

{
  "invoices": [
    {
      "id": 1,
      ...
    },
    {
      "id": 2,
      ...
    },
    ...
  ],
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "total_pages": 2,
    "total_count": 8
  }
}

5. Claim bitcoin surplus from Invoice

In case users transfer more that bitcoin_amount to the Invoice, the surplus amount can be claimed back to merchant’s bitcoin account

GET /invoices/:id/claim_bitcoin
GET /invoices?page=2&per=5

Parameters:

Sample response:

The bitcoin amount claimed is returned

{
  "amount": 0.25
}

6. Get Profile

Get merchant profile

GET /profile
{
  "id": 2,
  "email": "[email protected]",
  "first_name": "Test",
  "last_name": "Demo",
  "name": "Test Demo",
  "currency": "USD",
  "status": "approved",
  "settings": {
    "payments_callback": "https://merchant.com/callback"
  },
  ...
}

7. Update Notification URL

POST /payments_callback_url

Sample response:

{
  "callback": "https://merchant.com/callback"
}

Parameters:

Data POSTed to callback url

{
  "id": 1,
  "invoice_status": "payment_confirmed",
  "user_id": 2,
  "sub_account_id": 1,
  "bitcoin_address": "19wMMfLQ4Hu2XehHAbR3xY9UMEaaRLUMf4",
  "bitcoin_uri": "bitcoin:19wMMfLQ4Hu2XehHAbR3xY9UMEaaRLUMf4?amount=0.5",
  "name": "invoice name",
  "data": "any data",
  "amount": "500.0",
  "bitcoin_amount": 0.5,
  "bitcoin_amount_received": 0.5,
  "currency": "USD",
  "qrcode_address_url": "http://chart.googleapis.com/chart?chs=500x500&cht=qr&chl=19wMMfLQ4Hu2XehHAbR3xY9UMEaaRLUMf4",
  "qrcode_protocol_url": "http://chart.googleapis.com/chart?chs=500x500&cht=qr&chl=bitcoin:19wMMfLQ4Hu2XehHAbR3xY9UMEaaRLUMf4?amount=0.5",
  "paid_at": "2014-08-08T19:50:12.855+09:00",
  "created_at": "2014-08-08T19:40:12.855+09:00",
  "updated_at": "2014-08-08T19:40:12.855+09:00",
  "expired_at": "2014-08-08T20:10:12.855+09:00"
}