NAV

Bitwage API v1

______ _ _                                ___  ______ _____         
| ___ (_) |                              / _ \ | ___ \_   _|  
| |_/ /_| |___      ____ _  __ _  ___   / /_\ \| |_/ / | |   
| ___ \ | __\ \ /\ / / _` |/ _` |/ _ \  |  _  ||  __/  | |   
| |_/ / | |_ \ V  V / (_| | (_| |  __/  | | | || |    _| |_ 
\____/|_|\__| \_/\_/ \__,_|\__, |\___|  \_| |_/\_|    \___/ 
                            __/ |                                       
                           |___/                                        

Welcome to the Bitwage API v1 Documentation. Last Modified March 8, 2016.

Bitwage offers programmatic Access to its resources including Tickers, User, Worker, and Employer.

Applications using Bitwage API v1 include:

  1. Hubstaff: Time tracking software with screenshots, activity levels, and in-depth reports.
  2. Bitwage Android App: Access to Worker and Employer Resources from Android Device
  3. Bitwage IOS App: Access to Worker and Employer Resources from IOS Device

Authentication information visible on Bitwage Apps Page. For inquiries, submit a message using the contact form at www.bitwage.com.

Table of Contents

The Production entry point: https://api.bitwage.com/v1
The Sandbox entry point: https://api.bitwage.biz/v1

All requests must include an application/json Content-Type Header
All production requests must go over SSL.

Responses

200
See examples below for each API Path.
403
{"Unauthorized": [{"error_list": ["there was an error"]}]}
400
{"Bad Request": [{"error_list": ["there was an error"]}]}
500
{"Server Error": [{"error_list": ["there was an error"]}]}

Authentication:
1. API Key and Secret    2. Web Application Flow    3. Username and Password   

Tickers:
1. Tickers    2. Ticker   

User: Profile:
1. Profile    2. Companies   

Worker: History:
1. Payrolls    2. Savings    3. Card   

Worker: Spend:
1. Create    2. Commit   

Employer: Profile:
1. Profile    2. Linked Accounts    3. Deposit Address   

Employer: Workers:
1. Workers    2. Worker    3. Invite Worker    4. Email to ID   

Employer: Payrolls:
1. Payrolls    2. Payroll    3. Worker Payrolls    4. Create Payroll    5. Payroll Payment Method    6. Delete Payroll   

Employer: Invoices:
1. Invoices    2. Invoice    3. Approve Invoice   

Authentication

Access resources using:

Storing Credentials Securely

You should take great care to ensure your credentials are stored securely. If someone obtains your API Secret or OAUTH2 Access Token, they will be able to use Bitwage as if they were you. In particular, you should avoid storing these credentials in your code base (which gets added to version control) or in your database unless you have encrypted them securely. Separating credentials from your code base and database is a good practice. You can always regenerate your API key if you feel it has been compromised. Currently API key access is available only to Employer accounts and user must opt-in by generating an API Key and Secret.

Validating SSL Certificates

It is also very important that your application validates our SSL certificate when it connects over https. This helps prevent a man in the middle attack. If you are using a client library, this may be turned on by default, but you should confirm this. If you see a setting to ‘verify SSL’ you should always ensure it is set to true.

API Key + Secret

Bitwage offers API Key + Secret Authentication to access your own Bitwage Employer Account via the API.

  • Create a new API Key and Secret on the Bitwage Apps Page.
    • Enhanced Security Controls: can verify the actions and account information you wish to be accessible via the API and specify whether only certain IP Addresses have access. Coming Soon
    • Note: Users should never share API key + secret with anyone else.

Headers

>>> import time, hmac, hashlib
>>> ACCESS_NONCE = int(time.time() * 1e6)
>>> body = ''
>>> url = 'https://api.bitwage.com/v1/company/companies'
>>> message = str(ACCESS_NONCE) + url + ('' if not body else body)
>>> ACCESS_SIGNATURE=hmac.new(API_SECRET, message, hashlib.sha256).hexdigest()
>>> require 'openssl'
>>> ACCESS_NONCE = (Time.now.to_f * 1e6).to_i
>>> url = 'https://api.bitwage.com/v1/company/companies'
>>> message = ACCESS_NONCE.to_s + url + body.to_s
>>> ACCESS_SIGNATURE = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), API_SECRET, message)
>>> import javax.crypto.Mac;
>>> import javax.crypto.spec.SecretKeySpec;
>>> String ACCESS_NONCE = String.valueOf(System.currentTimeMillis());
>>> String url = "https://api.bitwage.com/v1/company/companies"
>>> String message = ACCESS_NONCE + url + (body != null ? body : "");
>>> Mac mac = Mac.getInstance("HmacSHA256");
>>> mac.init(new SecretKeySpec(API_SECRET.getBytes(), "HmacSHA256"));
>>> String ACCESS_SIGNATURE = new String(Hex.encodeHex(mac.doFinal(message.getBytes())));

Use the API Key and Secret to add three headers ACCESS_KEY, ACCESS_SIGNATURE, and ACCESS_NONCE to every API call that requires authentication. This scheme can be called “HMAC authentication.”

  1. The ACCESS_KEY header is your API Key.
  2. The ACCESS_NONCE header is a positive integer number that must increase with every request you make. Currently it must be submitted as a header. Coming Soon you can also submit it as a root-level parameter in a JSON POST request and as a GET parameter in the URL.
  3. The ACCESS_SIGNATURE header is a HMAC-SHA256 hash of the nonce concatentated with the full URL and body of the HTTP request, encoded using your API Secret.

Out-of-order Processing

Sometimes network traffic can cause near-simultaneous API calls to arrive out of order. Since the nonce must always be increasing, an API call with a higher nonce may arrive earlier than a separate call with a lower nonce if they are initiated very quickly together. When this happens, the second call will be dropped as invalid. To fix this, a separate expire parameter can be included, specifying a unix timestamp after which the call will not process. When the expire parameter is included, the nonce is ignored. We recommend setting the expire parameter to no greater than 15 minutes in the future to prevent replay attempts.

Web Application Flow

Bitwage is an OAuth 2.0 compliant service. Create your app on the Bitwage Apps Page.

Step 1 - Authorization

To prevent fraudulent transactions during the authentication process, we will only communicate with URLs that you have identified as trusted endpoints. Ensure the “OAuth 2.0 Redirect URLs” field for your application contains a valid callback URL to your server that is listening to complete your portion of the authentication workflow.

Once you save your configuration, your application will be assigned a unique “Client ID” and “Client Secret” value. Make note of these values — you will need to integrate them into the configuration files or the actual code of your application.

Step 2 - Requesting an Authorization Code

  #APP REQUESTS FROM USER A SUBSET OF THE FOLLOWING SCOPES 
  #Specify Your App's Scopes on Bitwage Apps Page (https://www.bitwage.com/profile/apps)

scope | meaning
--------- | -------
r_user_id | View User Profile
r_companies | View Companies
r_company_profile | View Company Profile
r_workers | View All Workers
r_company_payroll | View Specific Company Payrolls
r_worker_payrolls | View Worker Payrolls
r_worker | View Worker Information
r_company_payrolls | View All Company Payrolls
r_company_depositaddress | View Deposit Address
r_company_linkedaccounts | View Company Linked Accounts
r_company_invoice_approve | Approve Company Invoice
r_company_invoice | View Company Specific Invoice
r_company_invoices | View Company Invoices
w_company_invite | Send Invite to Worker
w_email_id | Get ID from Email
w_company_pay | Create Payroll Order
w_company_payroll_method | Select Payroll Order Method
w_payroll_delete | Delete Payroll Order

Once your application is properly configured, it’s time to request an authorization code. The authorization code is not the final token that you use to make calls to Bitwage with. It is used in the next step of the OAuth 2.0 flow to exchange for an actual access token. This is an important step because it provides assurance directly from Bitwage to the user that permission is being granted to the correct application, with the agreed-upon access to the member’s Bitwage profile.

HTTP Request

GET https://www.bitwage.com/authorize?client_id=client_id&state=state

Query Parameters

Parameter Type req? Description
client_id string yes Unique client ID assigned during step 1.
state string yes A cryptographically secure random string used to protect against cross-site request forgery attacks.

Once redirected, the user will be presented with Bitwage’s authentication dialog box. This identifies your application as well as outlines the particular member permissions that your application has requested. If desired, the logo and application name can be changed in your application configuration.

After the application is approved, the user will be redirected to the redirect_uri, which will have two important URL arguments that you will need to read from this request:

  • code: The OAuth 2.0 authorization code.
  • state: Value used to test against CSRF attacks.

Step 3 - Exchange Authorization Code for Request Token

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> body1={'code':'253508d4d37d40f9ba5d92a37ed8b46c', 'client_id': 'asdf123123iew', 'client_secret': 'asdf123043s', 'grant_type': 'authorization_code'}
>>> url = "https://api.bitwage.com/oauth2/token"
>>> headers = {}
>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Request Body JSON structured like this:

{
    "code": "253508d4d37d40f9ba5d92a37ed8b46c",
    "client_id": "asdf123123iew",
    "client_secret": "asdf123043s",
    "grant_type": "authorization_code"
}

Response JSON structured like this:

{
    "access_token": "de5d700499604da8b54e26b27bde9826"
}

Here, you can obtain a request token with the authorization code.

HTTP Request

POST https://api.bitwage.com/v1/oauth2/token

Request Body Parameters

Parameter Type req? Description
code string yes half-token from STEP 2
client_id string yes ID of used application
client_secret string yes secret of used application
grant_type string yes always ‘authorization_code’

Username and Password

Username and Password Authentication is designed for Third Party Apps (Mobile Applications) to act on behalf of individual users for their Worker and/or Employer resources.

  1. Get a Bitwage APP API Key and Secret from a Bitwage admin. (See Bitwage Apps Page)
  2. Create a new User API Key and Secret through the Login and TwoFA endpoints.
  3. Use this User API Key and Secret to authenticate to any API (Worker or Employer Resource)

Extra Headers for Username and Password Authentication

User-Agent

>>> useragent = 'testheader1'
>>> headers = {}
>>> headers['User-Agent'] = useragent

You must include a User-Agent Header when:

  1. Getting a User API Key and Secret (User: Login, Two Factor Authentication)
  2. You are using a User API Key and Secret to authenticate to any API.

Set to device’s user-agent or during testing set to arbitrary string.

USER_APP

>>> headers = {}
>>> headers['USER_APP'] = True

You must include a USER_APP Header when:

  1. Accessing an Employer API Resource (/v1/company).

Set to True (boolean)

User: Login

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/user/login?expire=" + str(expiration)
>>> headers = {}

# Authentication Headers:
>>> headers['ACCESS_KEY'] = APP_API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
>>> headers['User-Agent'] = USER_AGENT

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Request Body JSON structured like this:

{
  "username": "[email protected]",
  "password": "asjdfioas"
}

Response JSON structured like this:

{ 
    "username": "[email protected],
    "uuid": "d72f22b5-cb00-4168-8f82-50ca35956f3d"
}

For Authentication Headers follow API Key & Secret flow above, but use Bitwage APP Key and Secret given by Bitwage Support instead of the Key and Secret found in your Profile & Security page.
Login using username and password. Returns username and uuid. Use these with the access code to get the User Api Key and Secret

HTTP Request

POST https://api.bitwage.com/v1/user/login?expire=expiration

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.

Request Body Parameters

Parameter Type Description
username string bitwage username of the user
password string bitwage password of the user

User: Two Factor Authentication

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/user/twofa?expire=" + str(expiration)
>>> headers = {}

# Authentication Headers:
>>> headers['ACCESS_KEY'] = APP_API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
>>> headers['User-Agent'] = USER_AGENT

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Request Body JSON structured like this:

{
  "username": "[email protected]",
  "uuid": "d72f22b5-cb00-4168-8f82-50ca35956f3d",
  "access_token": 939393,
  "gcm_address": "asajdkf839829823f9dsa92399929292"
}

Response JSON structured like this:

{ 
    "username": "[email protected],
    "apikey": "b47a747c2c654adba50f41acd2939511",
    "apisecret": "80fe301033df46efb36355247044bbcb"
}

Use Bitwage APP API Key and APP API Secret for Authentication Headers. Submit the two factor authentication access token for a user along with the username, uuid from login call, and optional gcm_address, which is the ios or android push notification id. Returns username and user’s api key and secret. This User API Key and Secret works with User API. It doesn’t expire but can be revoked from Bitwage Portal under Profile & Security.

HTTP Request

POST https://api.bitwage.com/v1/user/twofa?expire=expiration

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.

Request Body Parameters

Parameter Type Description required?
username string bitwage username of the user yes
uuid string bitwage username of the user yes
access_token string bitwage username of the user yes
gcm_address string bitwage username of the user no

Tickers

Tickers

>>> url = "https://api.bitwage.com/v1/tickers"
>>> r = requests.get(url)
>>> print r

Response JSON structured like this:

{
    "XBTUSD": "687.45",
    "XBTEUR": "616.13",
    "USDEUR": "0.88",
    "EURPHP": "51.08",
    "EURINR": "74.84",
    "EURVND": "24841.15",
    "USDVND": "22300.00",
    "USDINR": "67.18",
    "EURMXN": "20.44",
    "EURUSD": "1.10",
    "datetimeUTC": "2016-07-02 08:40:59",
    "USDMXN": "18.35",
    "USDBRL": "3.24",
    "EURBRL": "3.60",
    "USDPHP": "45.78"
}

View all Bitwage tickers. No Authentication Required.

The format for quoting currency pairs is AAABBB, where AAA is the base currency and BBB is the quote currency. i.e. a currency pair shows how much of the quote currency is needed to purchase one unit of the base currency.

HTTP Request

GET https://api.bitwage.com/v1/tickers

Ticker

>>> url = "https://api.bitwage.com/v1/ticker/XBTUSD"
>>> r = requests.get(url)
>>> print r

Response JSON structured like this:

{
    "XBTUSD": "268.66",
    "datetimeUTC": "2015-07-08 01:20:05"
}

View specific Bitwage Currency Pair ticker.

Valid pairs shown in Tickers API.

HTTP Request

GET https://api.bitwage.com/v1/ticker/{currencypair}

User: Profile

Profile

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/company/userid?expire=" + str(expiration)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
  "user_id": "139343039393",
  "first_name": "George",
  "last_name": "Foogleshmidt",
  "date_of_birth": "02-13-2010",
  "phone_number": "19123457686",
  "street_address": "123 First Street",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94120"
}

View Profile Information of the user. User is defined as: owner of the API Key/Secret, user who created a User API Key/Secret via Username and Password authentication, or the Company Admin who created an Access Token by linking their Bitwage Company via Oauth2.

HTTP Request

GET https://api.bitwage.com/v1/company/userid?expire=expiration

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.

Companies

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/company/companies?expire=" + str(expiration)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
  "companies": [
    {
      "company_id": 12357567567,
      "company_name": "Najin"
    },
    {
      "company_id": 54358605335,
      "company_name": "Bape"
    }
  ],
  "default_company": 12357567567
}

View companies user is an admin of. Default Company is either 0 or the company_id of the desired company to be shown in Employer sidebar. User is defined as: owner of the API Key/Secret, user who created a User API Key/Secret via Username and Password authentication, or the Company Admin who created an Access Token by linking their Bitwage Company via Oauth2.

HTTP Request

GET https://api.bitwage.com/v1/company/companies?expire=expiration

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.

Worker: History

Payrolls

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/user/payrolls?expire=" + str(expiration)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
>>> headers['User-Agent'] = USER_AGENT

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
    "payroll_fulfilled": 5,
    "payroll_not_fulfilled": 14,
    "total_fulfilled": 15.02,
    "total_not_fulfilled": 560.77,
    "total_by_currency": {
        "fulfilled":{
            "USD": 15.02,
            "EUR":0.0
        },
        "not_fulfilled":{
            "USD":560.77,
            "EUR":0.0
        }
    },
    "bpicompanyname": "Payroll Individual",
    "bpicompanyid": 6471725441089536,
    "userpayrolls": [
        {
            "id": 5603420492791808,
            "payroll_id": 5040470539370496,
            "company_id": 6471725441089536,
            "company_name": u'ΠατρονομοςBPI',
            "payment_type": "ach",
            "created": "2015-06-04T20:29:59.220184",
            "received": true,
            "datereceived": "2015-06-04T20:29:59.315871",
            "approved": true,
            "dateapproved": "2015-06-04T20:30:15.730674",
            "broadcasted": true,
            "fulfilled": true,
            "datefulfilled": "2015-06-04T20:31:59.220184",
            "currency":"USD",
            "amount_usd": 0.02,
            "amount_btc": 0.02253044,
            "transaction_id": "e0cff7a55521f7f4b44334d74cd234dda88f596a2a2559820addb8399560fcdb",
            "distobj_list": [
                {
                    "percentage":100,
                    "usercompany_wallet": "1CK6k5wmEqYjEbNrY25EdwNFahfdHm7p52",
                    "payment_outlet": "",
                    "paymentoutlet_orderid": "",
                    "distributionobjects": True,
                    "userpayrolldistributionobjects": True,
                    "amount_usd": 0.02,
                    "amount_btc": 0.02253044,
                    "country": "Bitcoin",
                    "currency": "BTC"
                }
            ]
        }
    ]
}

For this endpoint: use User’s API Key and Secret obtained from TwoFA. View Payrolls User has received through Bitwage. amount_usd is currency-agnostic amount not just USD.

HTTP Request

GET https://api.bitwage.com/v1/user/payrolls?expire=expiration

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.

Savings

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/user/savings?expire=" + str(expiration)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
>>> headers['User-Agent'] = USER_AGENT

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
  "brobject": [
    {
      "currency": "BTC",
      "lastTransactionAt": "2015-07-12T03:30:10.260Z",
      "id": "d15a72bb-ff75-416c-9f29-f11f35ccd3d5",
      "balance": "0.00050453",
      "address": {
        "bitcoin": "1BEKHSQRRRJzTmGhgwExFFPctMiyaJGZcw"
      },
      "addresses": [
        {
          "network": "bitcoin",
          "id": "1BEKHSQRRRJzTmGhgwExFFPctMiyaJGZcw"
        }
      ],
      "available": "0.00050453",
      "label": "BTC card",
      "normalized": [
        {
          "balance": "0.14",
          "available": "0.14",
          "currency": "USD"
        }
      ],
      "settings": {
        "starred": true,
        "position": "1"
      }
    }
  ],
  "brusername": "joetil",
  "brnorm_available": 11.34,
  "brnorm_currency": "USD",
  "brobjecttx": [
    {
      "type": "deposit",
      "params": {
        "rate": "1.00",
        "currency": "BTC",
        "txid": "e6bf08bf748a6a6ec414105edd0510dc4256df288a78bc3c69bde33483677c9e",
        "type": "external/in",
        "margin": "0.00",
        "ttl": 30000,
        "pair": "BTCBTC",
        "progress": "1"
      },
      "id": "7d981fb4-b301-4803-b0b8-7e81e5a62e1c",
      "origin": {
        "rate": "1.00",
        "commission": "0.00",
        "type": "external",
        "description": "Bitcoin Network",
        "amount": "0.00009916",
        "currency": "BTC",
        "sources": [],
        "fee": "0.00",
        "base": "0.00009916"
      },
      "status": "completed",
      "createdAt": "2015-07-12T03:30:10.210Z",
      "message": null,
      "destination": {
        "rate": "1.00",
        "currency": "BTC",
        "type": "card",
        "description": "George Lind",
        "amount": "0.00009916",
        "username": "joetil",
        "commission": "0.00",
        "isMember": true,
        "fee": "0.00",
        "base": "0.00009916",
        "CardId": "d15a72bb-ff75-416c-9f29-f11f35ccd3d2"
      },
      "normalized": [
        {
          "rate": "298.15500",
          "amount": "0.03",
          "currency": "USD",
          "commission": "0.00"
        }
      ],
      "denomination": {
        "rate": "1.00",
        "amount": "0.00009916",
        "pair": "BTCBTC",
        "currency": "BTC"
      }
    }
  ],
  "brnorm_balance": 11.34
}

For this endpoint: use User’s API Key and Secret obtained from TwoFA. View Savings Account Details and Txs of User.

HTTP Request

GET https://api.bitwage.com/v1/user/savings?expire=expiration

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.

Card

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/user/card?expire=" + str(expiration)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
>>> headers['User-Agent'] = USER_AGENT

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
  "xapoobject": {
    "type": "wallet",
    "account_permissions": [
      {
        "id_user": 1231234,
        "permissions": [
          "admin",
          "start_payments",
          "sign_payments"
        ]
      }
    ],
    "btcaverage24hr": "291.08",
    "id": 734841,
    "account_owners": [
      {
        "owner_type": "user",
        "owner_id": 1231234
      }
    ],
    "currency": "BTC",
    "active": true,
    "available_balance": "0.04414084",
    "creation_date": "2015-02-21 22:36:52",
    "primary_address": "3EA7trojxbFEJUMd7ETxrWFJVyVL4gUPwE",
    "access_control": [
      {
        "owner_type": "user",
        "owner_id": 1231234,
        "roles": [
          "admin",
          "start_payments",
          "sign_payments"
        ]
      }
    ],
    "owner_id": 1231234,
    "debitcard_id": 1138,
    "name": "Personal Wallet",
    "short_name": "X",
    "balance": "0.04414084",
    "is_primary": true,
    "owner_type": "user",
    "text_color": "ff3b30",
    "avail_balance_USD": "12.85",
    "bg_color": "222222"
  },
  "xapoobjecttx": [
    {
      "status": "completed",
      "base_currency": null,
      "generic_type": "credit",
      "from": {
        "type": "btc_address",
        "id": "1HD2reUvn1WndU6495remQ42hEFCvXtNVw"
      },
      "description": "Money from 1HD2reUvn1WndU6495remQ42hEFCvXtNVw",
      "exchange_rate": null,
      "txid": "a83307668d6b2336c0ea9bb7f9a2561d3435de46836c0e1b34554c0c4feaf3cc",
      "exchange_amount": null,
      "notes": null,
      "amount": "0.00011108",
      "datetime": "2015-07-07 08:18:51",
      "rejection_reason": null,
      "currency": "BTC",
      "order_type": "payment_received",
      "vout": 1,
      "to": {
        "destination_type": "btc_address",
        "to_account": "734841",
        "destination_id": "3FGwMF9KErVDNtTFHdk5yeQeuDXuR7S7hu"
      },
      "id": 61124801
    }
  ]
}

For this endpoint: use User’s API Key and Secret obtained from TwoFA. View Card Details and Txs of User.

HTTP Request

GET https://api.bitwage.com/v1/user/card?expire=expiration

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.

Worker: Spend

Create

>>> import time, requests, json
>>> invoice_id = <insert invoice_id here as int>
>>> expiration = int(time.time()+300)
>>> body1={'invoice_id': str(invoice_id)}
>>>body = json.dumps(body1)
>>> url = "https://api.bitwage.com/v1/user/spend/create?expire=" + str(expiration)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
>>> headers['User-Agent'] = USER_AGENT

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.post(url,json=body1,headers=headers)
>>> print r

Request Body JSON structured like this:

{
    "input": "random",
    "output": "cloudspending",
    "amount_usd": ".12"
}

Response JSON structured like this:

{
  "destination": "3GT1MzEPGbxXx8BPoCBnvYparWKwVssss",
  "amount_usd": ".12",
  "uuid": "8ec399fa-e606-4fc6-874d-50300d0ddddd",
  "cardid": "93eacee0-b6c5-4c58-9c3f-5a170feeeee",
  "user_id": 5629499534213333,
  "cardlabel": "XAU card",
  "txid": "fab5aecf-54b5-4de9-9b06-18245d1ccccc"
}

For this endpoint: use User’s API Key and Secret obtained from TwoFA. Creates a transaction where source is a savings account card and destination is xapo debit card. Transaction is not broadcasted until Committed. The Card is the first card (alphabetically down) where normalized USD balance is sufficient Body must be in correct order as below (ordered dict). Amount USD must be string

HTTP Request

POST https://api.bitwage.com/v1/user/spend/create?expire=expiration

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.

Request Body Parameters

Parameter Type Description
input string input name
output string output name
amount_usd string amount usd to send

Commit

>>> import time, requests, json
>>> invoice_id = <insert invoice_id here as int>
>>> expiration = int(time.time()+300)
>>> body1={'invoice_id': str(invoice_id)}
>>>body = json.dumps(body1)
>>> url = "https://api.bitwage.com/v1/user/spend/commit?expire=" + str(expiration)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
>>> headers['User-Agent'] = USER_AGENT

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.post(url,json=body1,headers=headers)
>>> print r

Request Body JSON structured like this:

{
    "uuid": "8ec399fa-e606-4fc6-874d-50300d0ddddd",
    "access_token": "8888888",
    "user_id": 5629499534213333,
    "txid": "fab5aecf-54b5-4de9-9b06-18245d1ccccc",
    "cardid": "93eacee0-b6c5-4c58-9c3f-5a170feeeee",
    "destination": "3GT1MzEPGbxXx8BPoCBnvYparWKwVssss",
    "amount_usd": ".12",
    "card_label": "XAU card"
}

Response JSON structured like this:

{
  "status": "completed",
  "message": "Successfully sent .12 USD from Savings Account (XAU card) to Spending Card (3GT1MzEPGbxXx8BPoCBnvYparWKwVtpvPr)"
}

For this endpoint: use User’s API Key and Secret obtained from TwoFA. Commits a transaction where source is a savings account card and destination is xapo debit card. The Card is the first card (alphabetically down) where normalized USD balance is sufficient Body must be in correct order as below (ordered dict). Amount USD must be string

HTTP Request

POST https://api.bitwage.com/v1/user/spend/commit?expire=expiration

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.

Request Body Parameters

Parameter Type Description
access_token string access token from two factor
uuid string uuid obtained from tx create
user_id int int obtained from tx create
txid string string obtained from tx create
cardid string string obtained from tx create
destination string string obtained from tx create
amount_usd string string obtained from tx create
card_label string string obtained from tx create

Employer: Profile

Profile

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/company?expire=" + str(expiration) + "&company_id=" + str(company_id)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
  "company_name": "Example Company",
  "company_id": "6403555720167424",
  "street_address": "123 Main St.",
  "country": "US",
  "city": "Sunnyvale",
  "state": "CA",
  "zip": "12345",
  "website_url": "http://www.example.com",
  "email": "[email protected]",
  "phone": "+1 (123) 456-7891",
  "ein": "123151244",
  "default_payment_method": "ach_credit"
}

View profile information of specified company. Default Payment Method options are: “ach_credit”, “ach_debit”, “wire”, “bitcoin”, “credit_card”

HTTP Request

GET https://api.bitwage.com/v1/company?expire=expiration&company_id=company_id

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.

Linked Accounts

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/company/linkedaccounts?expire=" + str(expiration) + "&company_id=COMPANYID"
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
  "type": "credit_card",
  "brand": "Visa",
  "last4": 1234,
  "id": 12345678
}

View accounts that the Employer has linked.

HTTP Request

GET https://api.bitwage.com/v1/company/linkedaccounts?expire=expiration&company_id=COMPANYID

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.

Deposit Address

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> payroll_id = <insert payroll ID here as int>
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/company/depositaddress?expire=" + str(expiration) + "&company_id=" + str(company_id)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{ 
  "depositaddr_bitcoin": "1IDSHSQRRRJzTmGkkkExFFPctMiyaJpppp", 
  "company_id": "5096012251136111", 
  "card_currency": "BTC", 
  "card_id": "k24a72bb-ff75-416c-9f29-f11f35ceeeee"
}

View Employer Deposit Address. This corresponds to the company admin’s Bitcoin currency card within their Cloud Savings Account.

HTTP Request

GET https://api.bitwage.com/v1/company/depositaddress?expire=expiration&company_id=company_id

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.

Employer: Workers

Workers

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/company/workers?expire=" + str(expiration) + "&company_id=" + str(company_id)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
  "workers": [
    {
      "email": "[email protected]",
      "user_id": 2885074604081128,
      "role": "admin"
    },
    {
      "email": "[email protected]",
      "user_id": 1230984041000002,
      "role": "admin"
    }
  ],
  "meta": {
    "curr_page":1,
    "next_page":"",
    "total_pages":1
  }
}

View all workers of specified Employer.

HTTP Request

GET https://api.bitwage.com/v1/company/workers?expire=expiration&company_id=company_id

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.

Worker

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> expiration = int(time.time()+300)
>>> user_id = <insert user_id as int>
>>> url = "https://api.bitwage.com/v1/company/worker?expire=" + str(expiration) + "&company_id=" + str(company_id) + "&user_id=" + str(user_id)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
  "first_name": "John",
  "last_name": "Smith",
  "email": "[email protected]",
  "dob": "2000-01-31",
  "phone_number": "+1 (123) 345-9539",
  "street_address": "123 Main St",
  "role": "admin",
  "worker_id": "5629499534213120",
  "total_not_fulfilled": 1000.0,
  "total_fulfilled": 0.0,
  "total_by_currency": {
    "fulfilled": {
        "USD":0.0,
        "EUR":0.0
    },
    "not_fulfilled": {
        "USD":1000.0,
        "EUR":0.0
    }
  },
  "receive_method_entered": false
}

View information of specified worker.

HTTP Request

GET https://api.bitwage.com/v1/company/worker?expire=expiration&company_id=company_id&user_id=user_id

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.
user_id Number The worker’s ID in the Bitwage database.

Invite Worker

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> expiration = int(time.time()+300)
>>> body1={'to_invite':[{'email': [email protected]','role': 'admin'}]}
>>>body = json.dumps(body1)
>>> url = "https://api.bitwage.com/v1/company/workers/invite?expire=" + str(expiration) + "&company_id=" + str(company_id)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.post(url,json=body1,headers=headers)
>>> print r

Request Body JSON structured like this:

{
    "to_invite": [
        {
            "email": "[email protected]",
            "role": "admin"
        }
    ]
}

Response JSON structured like this:

{
  "invite_log": [
    {
      "email": "[email protected]",
      "status": "sent"
    }
  ]
}

Invite workers to your Employer profile on Bitwage.

HTTP Request

POST https://api.bitwage.com/v1/company/workers/invite?expire=expiration&company_id=company_id

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.

Request Body Parameters

Parameter Type Description
email string email of user to invite
role string role of user to invite (contractor, admin, or employee)

Email to ID

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> expiration = int(time.time()+300)
>>> body1={"emails": ["[email protected]", "[email protected]"]}
>>>body = json.dumps(body1)
>>> url = "https://api.bitwage.com/v1/company/workers/emailtoid?expire=" + str(expiration) + "&company_id=" + str(company_id)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.post(url,json=body1,headers=headers)
>>> print r

Request Body JSON structured like this:

{
    "emails": [
        "[email protected]"
    ]
}

Response JSON structured like this:

{
  "success": [
    {
      "email": "[email protected]",
      "user_id": 6685030696878080
    }
  ],
  "failure": [
    {
      "email": "[email protected]",
      "error": "Worker does not exist."
    }
  ]
}

HTTP Request

POST https://api.bitwage.com/v1/company/workers/emailtoid?expire=expiration&company_id=company_id

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.

Request Body Parameters

Parameter Type Description
email string email of user that you want ID from.

Employer: Payrolls

Payrolls

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/company/payrolls?expire=" + str(expiration) + "&company_id=" + str(company_id)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
  "company_id": "6403555720167424",
  "company_name": "Example Company",
  "payroll_not_fulfilled": 0,
  "payroll_fulfilled": 33,
  "total_fulfilled": 0.0,
  "total_not_fulfilled": 1000.03,
  "total_by_currency": {
    "fulfilled": {
        "USD":0.0,
        "EUR":0.0
    },
    "not_fulfilled": {
        "USD":1000.03,
        "EUR":0.0
    }
  },
  "payrolls": [
    {
      "amount": 0.03,
      "currency": "USD",
      "id": 4838400918028288,
      "time_created": "2015-07-16T02:07:31.937968",
      "userpayrolls": [
           {
               "user_email": "[email protected]", 
               "user_id": 5677071464398848, 
               "userpayroll_id": 6523493654986752
           }
       ]
    },
    {
      "amount": 1.00,
      "currency": "USD",
      "id": 4234242238028288,
      "time_created": "2015-07-16T02:08:36.923968",
      "userpayrolls": [
           {
               "user_email": "[email protected]", 
               "user_id": 5677071364398848, 
               "userpayroll_id": 6523423654986752
           }
       ]
    }
  ],
  "meta":{
    "curr_page":1,
    "next_page":"",
    "total_pages":1
  }
}

View all payrolls for specified Employer.

HTTP Request

GET https://api.bitwage.com/v1/company/payrolls?expire=expiration&company_id=company_id

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.

Payroll

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> payroll_id = <insert payroll ID here as int>
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/company/payroll?expire=" + str(expiration) + "&company_id=" + str(company_id) + "&payroll_id=" + str(payroll_id)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
  "time_created": "2015-06-30T00:48:01.265676",
  "date_received": "2015-06-20",
  "date_processed": "2015-06-21",
  "date_fulfilled": "2015-06-22",
  "total_amount": 1.03,
  "currency": "USD",
  "userpayrolls": [
    {
      "amount": 0.03,
      "currency": "USD",
      "user_id": 4838400918028288,
      "email": "[email protected]"
    },
    {
      "amount": 1.00,
      "currency": "USD",
      "user_id": 4234242238028288,
      "email": "[email protected]"
    }
  ],
  "payment_type": "ach",
  "payment_details": {
    "printOnCheck": "Individual",
    "address": "123 Main St.",
    "checkNum": "3333333333",
    "city": "Los Angeles",
    "memo": "A+",
    "phone": "+1 (123) 633-0123",
    "bankAccNum": "XXXXXX2222",
    "bankRoute": "1111111111",
    "state": "CA",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Smith",
    "zipcode": "95070"
  },
  "meta": {
    "curr_page":1,
    "next_page":"",
    "total_pages":1
  }
}

View information about a specified payroll.

HTTP Request

GET https://api.bitwage.com/v1/company/payroll?expire=expiration&company_id=company_id&payroll_id=payroll_id

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.
payroll_id Number The payroll’s ID in the Bitwage database.

Worker Payrolls

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> expiration = int(time.time()+300)
>>> user_id = <insert user ID here as int>
>>> url = "https://api.bitwage.com/v1/company/worker/payrolls?expire=" + str(expiration) + "&company_id=" + str(company_id) + "&user_id=" + str(user_id)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
  "company_id": "6403555720167424",
  "company_name": "Example Company",
  "payroll_not_fulfilled": 33,
  "payroll_fulfilled": 0,
  "total_fulfilled": 0.0,
  "total_not_fulfilled": 10000.06,
  "total_by_currency": {
    "fulfilled": {
        "USD":0.0,
        "EUR":0.0
    },
    "not_fulfilled": {
        "USD":10000.06,
        "EUR":0.0
    }
  },
  "payrolls": [
    {
      "amount": 0.03,
      "currency": "USD",
      "id": 4838400918028288,
      "time_created": "2015-07-16T02:07:31.937968",
      "userpayrolls": [
           {
               "user_email": "[email protected]", 
               "user_id": 5677071364398842, 
               "userpayroll_id": 6523423654986751
           }
       ]
    },
    {
      "amount": 1.00,
      "currency": "USD",
      "id": 4234242238028288,
      "time_created": "2015-07-16T02:08:36.923968",
      "userpayrolls": [
           {
               "user_email": "[email protected]", 
               "user_id": 5677071364398842, 
               "userpayroll_id": 6523423654986753
           }
       ]
    }
  ],
  "meta": {
    "curr_page":1,
    "next_page":"",
    "total_pages":1
  }
}

View all payrolls where the specified worker is a recipient.

HTTP Request

GET https://api.bitwage.com/v1/company/worker/payrolls?expire=expiration&company_id=company_id&user_id=user_id

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.
user_id Number The worker’s ID in the Bitwage database.

Create Payroll

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> paywithid = <insert paywithid here as true or false>
>>> deleteifnotmethod = <insert deleteifnotmethod here as true or false>
>>> expiration = int(time.time()+300)
>>> body1={'to_pay':[{'email': [email protected]','amount_usd': '10.0'}]} #email or user_id depending on value of paywithid. amount_usd as string
>>>body = json.dumps(body1)
>>> url = "https://api.bitwage.com/v1/company/workers/pay?expire=" + str(expiration) + "&company_id=" + str(company_id) + "&paywithid=" + str(paywithid) + "&deleteifnotmethod=" + str(deleteifnotmethod)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.post(url,json=body1,headers=headers)
>>> print r

Request Body JSON structured like this:

{
    "to_pay": [
        {
            "email": "[email protected]",
            "amount_usd": "10.0"
        }
    ]
}

Response JSON structured like this:

{
  "payroll_id": 5822463824887808,
  "status":'created' #'created' or 'deleted'
  "suborder_list": [
    {
      "email": "[email protected]",
      "amount_usd": "10"
    }
  ],
  "total_amount": 10.0,
  "currency":"USD",
  "num_suborders": 1,
  "payment_method": "ach_credit",
  "payment_method_set_msg":"" #specifies reason if default_payment_method is not set as payment_method
}

Create a payroll order for your company. Will attempt to set Payment Method of the Order to the Company’s Default Payment Method. Default Payment Method options are: “None”, “ach_credit”, “ach_debit”, “wire”, “bitcoin”, “credit_card”. Only the options “ach_credit”, “wire”, and “credit_card” can possibly be automatically set as the Payment Method of the order via API. If fails to set Payment Method, will return a Message Explanation or optionally will delete the Order and not send an Email Notification.

HTTP Request

POST https://api.bitwage.com/v1/company/workers/pay?expire=expiration&company_id=company_id&paywithid=paywithid

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.
paywithid Boolean (optional) If 'true’, specifies option to pay with userID. If nothing specified, defaults to email.
deleteifnotmethod Boolean (optional) If 'true’, specifies that if payment method not automatically set via Default Payment Method to delete Payroll and not send email notification.

Request Body Parameters

Parameter Type Description
email string email of user to pay
user_id string user_id of user to pay (use either email or user_id)
amount_usd string amount usd to pay

Payroll Payment Method

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> payroll_id = <insert payroll ID here as int>
>>> expiration = int(time.time()+300)
>>> body1={'payment_method':'wire'} //valid payment_methods: 'wire', 'ach_credit', 'credit_card'
>>>body = json.dumps(body1)
>>> url = "https://api.bitwage.com/v1/company/workers/pay?expire=" + str(expiration) + "&company_id=" + str(company_id) + "&paywithid=" + str(paywithid)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.post(url,json=body1,headers=headers)
>>> print r

Request Body JSON structured like this:

{
    "payment_method": "wire"
}

Response JSON structured like this:

{
  "status": "success",
  "payroll_id": "5822463824887808",
  "payment_method": "wire"
  "payment_method_set_msg": "" #only returned if status == 'failure'
}

Specify Payment Method for a Payroll Order. This is required for Bitwage to process order. Bitwage offers: bitcoin transfer, wire, ach credit, ach debit, and credit card, but only wire, ach credit and credit card are available through the API right now.

HTTP Request

POST https://api.bitwage.com/v1/company/payroll/method?expire=expiration&company_id=company_id&payroll_id=payroll_id

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.
payroll_id Number The payroll ID in the Bitwage database.

Request Body Parameters

Parameter Type Description
payment_method string payment_method to set for payroll. valid methods: 'wire’, 'ach_credit’, 'credit_card’

Delete Payroll

>>> import time, requests, json
>>> payroll_id = <insert payroll_id here as int>
>>> expiration = int(time.time()+300)
>>> body1={'to_delete':[payroll_id]} //list of payroll_ids to delete
>>>body = json.dumps(body1)
>>> url = "https://api.bitwage.com/v1/company/payroll/delete?expire=" + str(expiration)
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.post(url,json=body1,headers=headers)
>>> print r

Request Body JSON structured like this:

{
    "to_delete": [ 
        "5822463824887809"
    ]
}

Response JSON structured like this:

{
  "success": [5822463824887809],
  "failure": [
    {
      "payroll_id": 5822463824887808
    }
  ]
}

Delete a payroll order for your company. Cannot delete a payroll already approved.

HTTP Request

POST https://api.bitwage.com/v1/company/payroll/delete?expire=expiration

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.

Request Body Parameters

Parameter Type Description
payroll_id int payroll_id of payroll to delete

Employer: Invoices

Invoices

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/company/invoices?expire=" + str(expiration) + "&company_id=COMPANYID"
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
  "company": {
    "id": "6122080743456768",
    "name": "Hello, Inc."
  }
  "invoices": 
    [
      {
        "id": 5725981679550464, 
        "worker": {
            "id": 6122080743456722,
            "email": "[email protected]"
        },
        "total_amount_fiat": 1000.0, 
        "time_created": "2016-03-07 22:10:29.049796", 
        "currency": "USD",
        "payroll_id": 6122080743456555,
        "due_date": "2016-03-07",
        "approved": false
      }
    ]
}

View all invoices that users have sent to your company.

HTTP Request

GET https://api.bitwage.com/v1/company/invoices?expire=expiration&company_id=COMPANYID

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.

Invoice

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/company/invoice?expire=" + str(expiration) + "&company_id=COMPANYID" + "&invoice_id=INVOICEID"
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.get(url, headers = headers)
>>> print r

Response JSON structured like this:

{
  "id": 5769603078684633,
  "company": {
    "id": 5769603078684622,
    "name": "Test, Inc",
    "phone_number": "+1 (204) 200-3963",
    "street_address": "123 First Street",
    "city": "Knoxville",
    "state": "TN",
    "zip": "34443",
    "website_url": "http://example.com",
    "ein": "12-1234567",
    "email" "[email protected]": 
  },
  "worker": {
    "id": 5769603078684611,
    "email": "[email protected]"
  },
  "line_items":[{
    "time": 20.0,
    "amount_fiat": 1000.0,
    "amountpertime": 50.0,
    "currency": "USD",
    "description": "front end development"
  }],
  "time_created": "2016-03-07 22:10:29.049796",
  "currency": "USD", 
  "amount": 1000.0, 
  "due date": "2016-03-07", 
  "approved": true
}

View specific invoice that a worker has sent to your company.

HTTP Request

GET https://api.bitwage.com/v1/company/invoices?expire=expiration&company_id=COMPANYID

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.
invoice_id Number The invoice id of the specific invoice.

Approve Invoice

>>> import time, requests, json
>>> invoice_id = <insert invoice_id here as int>
>>> expiration = int(time.time()+300)
>>> body1={'invoice_id': str(invoice_id)}
>>>body = json.dumps(body1)
>>> url = "https://api.bitwage.com/v1/company/invoice/approve?expire=" + str(expiration) + "&company_id=COMPANYID"
>>> headers = {}

# Authentication Headers for Key/Secret:
>>> headers['ACCESS_KEY'] = API_KEY
>>> headers['ACCESS_SIGNATURE'] = ACCESS_SIGNATURE
>>> headers['ACCESS_NONCE'] = ACCESS_NONCE
# if using User API Key/Secret
>>> headers['User-Agent'] = USER_AGENT
>>> headers['USER_APP'] = True

# Authentication Headers for Open Authentication
>>> headers['Authorization'] = 'Bearer ' + ACCESS_TOKEN

>>> headers['Content-Type'] = 'application/json'
>>> r = requests.post(url,json=body1,headers=headers)
>>> print r

Request Body JSON structured like this:

{
    "invoice_id": "2384192341092834"
}

Response JSON structured like this:

{
    "invoice": {
        "id": 5822463824887808,
        "status": "approved", 
        "currency": "USD", 
        "total_amount_fiat": 10000.0
    },
    "payroll": {
        "id": 5822463824887833,
        "total_amount": 10000.0
        "currency": "USD", 
        "status": "created", 
        "num_suborders": 1,
        "suborder_list": [{
            "amount_usd": "10000.00", 
            "user_id": 5707702298738622, 
            "email": "[email protected]"
        }],
        "payment_method":"None",
        "payment_method_set_msg": "None or Unsupported Default Payment Method "
    }
}

Approve an Invoice. Create a payroll order for your company. Will attempt to set Payment Method of the Order to the Company’s Default Payment Method. Default Payment Method options are: “None”, “ach_credit”, “ach_debit”, “wire”, “bitcoin”, “credit_card”. Only the options “ach_credit”, “wire”, and “credit_card” can possibly be automatically set as the Payment Method of the order via API. If fails to set Payment Method, will return a Message Explanation.

HTTP Request

POST https://api.bitwage.com/v1/company/invoice/approve?expire=expiration&company_id=COMPANYID

Query Parameters

Parameter Type Description
expiration Unix Timestamp Specifies the time after which the call will not process. When included, the nonce is ignored.
company_id Number The company’s ID in the Bitwage database.

Request Body Parameters

Parameter Type Description
invoice_id int ID of invoice you want to approve.



Bitwage