Public API Bitwage Payroll

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

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

Applications using Bitwage Payroll Public API v1 include:

Hubstaff: Time tracking software with screenshots, activity levels, and in-depth reports.
Bitwage Android App: Access to Worker and Employer Resources from Android Device
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.

Authentication

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.

Access resources using:

API Key and Secret (For accessing your own resources)
Web Application Flow (For Apps accessing other Employers)
Username and Password (For Apps accessing other Workers and/or Employers)

API Key + Secret

Bitwage offers API Key + Secret Authentication to access your own Bitwage Worker and Employer Resources 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.”

The ACCESS_KEY header is your API Key.
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.
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://team.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_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://team.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

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

{
    "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.

Get a Bitwage APP API Key and Secret from a Bitwage admin. (See Bitwage Apps Page)
Create a new User API Key and Secret through the Login and TwoFA endpoints.
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:

Getting a User API Key and Secret (User: Login, Two Factor Authentication)
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:

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

Set to True (boolean)

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

{
  "username": "joeshoe@gmail.com",
  "password": "asjdfioas"
}

{ 
    "username": "joeshoe@gmail.com,
    "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

{
  "username": "joeshoe@gmail.com",
  "uuid": "d72f22b5-cb00-4168-8f82-50ca35956f3d",
  "access_token": 939393,
  "gcm_address": "asajdkf839829823f9dsa92399929292"
}

{ 
    "username": "joeshoe@gmail.com,
    "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

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

{
    "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

{
    "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

{
  "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

{
  "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.

BPI Company View

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/user/bpi_company/view?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

{
  "bpiemplist": [
    {
      "ppname": "payroll provider name",
      "created": "2016-09-09 05:33:08.238780",
      "ppwebsite": "https://team.bitwage.com/",
      "employer": "test employer",
      "employerwebsite": "https://team.bitwage.com/",
      "employercurrency": "USD",
      "jobrole": "Employee",
      "bpionboardid": 6253195365934046,
      "order": 1
    }
  ]
}

View list of BPI companies for authenticated user.

HTTP Request

GET https://api.bitwage.com/v1/user/bpi_company/view?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.

BPI Company Edit

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> expiration = int(time.time()+300)
>>> body1={"jobrole":"Employee", "bpionboardid":"6253193365974016", "employer":"test employer11", "employerwebsite": "https://team.bitwage.com/", "employercurrency": "USD","ppname":"payroll provider","ppwebsite":"https://team.bitwage.com/"}
>>> body = json.dumps(body1)
>>> url = "https://api.bitwage.com/v1/user/bpi_company/edit?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

{
  "bpiemplist": [
    {
      "ppname": "payroll provider name",
      "created": "2016-09-09 05:33:08.238780",
      "ppwebsite": "https://team.bitwage.com/",
      "employer": "test employer",
      "employerwebsite": "https://team.bitwage.com/",
      "employercurrency": "USD",
      "jobrole": "Employee",
      "bpionboardid": 6253195365934046,
      "order": 1
    }
  ]
}

Edit BPI company for authenticated user as specified by param bpionboardid.

HTTP Request

POST https://api.bitwage.com/v1/user/bpi_company/edit?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
employer	string	employer name to set
ppname	string	payroll provider name to set
employerwebsite	string	employer website to set
ppwebsite	string	payroll provider website to set
employercurrency	string	employer currency to set
jobrole	string	job role to set
bpionboardid	string	if of bpionboard object

BPI Company Add

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> expiration = int(time.time()+300)
>>> body1={"jobrole":"Employee", "employer":"test employer11", "employerwebsite": "https://team.bitwage.com/", "employercurrency": "USD","ppname":"payroll provider","ppwebsite":"https://team.bitwage.com/"}
>>> body = json.dumps(body1)
>>> url = "https://api.bitwage.com/v1/user/bpi_company/add?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

{
  "bpiemplist": [
    {
      "ppname": "payroll provider name",
      "created": "2016-09-09 05:33:08.238780",
      "ppwebsite": "https://team.bitwage.com/",
      "employer": "test employer",
      "employerwebsite": "https://team.bitwage.com/",
      "employercurrency": "USD",
      "jobrole": "Employee",
      "bpionboardid": 6253195365934046,
      "order": 1
    }
  ]
}

Add BPI company for authenticated user.

HTTP Request

POST https://api.bitwage.com/v1/user/bpi_company/add?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
employer	string	employer name to set
ppname	string	payroll provider name to set
employerwebsite	string	employer website to set
ppwebsite	string	payroll provider website to set
employercurrency	string	employer currency to set
jobrole	string	job role to set

BPI Company Delete

>>> import time, requests, json
>>> company_id = <insert company ID here as int>
>>> expiration = int(time.time()+300)
>>> body1={"bpionboardid":"6253193365974016"}
>>> body = json.dumps(body1)
>>> url = "https://api.bitwage.com/v1/user/bpi_company/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

{
    "status": "success"
}

Delete BPI company for authenticated user.

HTTP Request

POST https://api.bitwage.com/v1/user/bpi_company/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
bpionboardid	string	id of bpionboard object to delete

Add Card

>>> import time, requests, json
>>> stripeToken = <insert stripeToken here>
>>> expiration = int(time.time()+300)
>>> body1={"stripeToken":"6253193365974016"}
>>> body = json.dumps(body1)
>>> url = "https://api.bitwage.com/v1/user/link/creditcard?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

{
    'userlinkcreditcardsuccess': True
}

Add card for authenticated user.

HTTP Request

POST https://api.bitwage.com/v1/user/link/creditcard?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
stripeToken	string	stripeToken of card to add

View Card

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/user/viewlinkedcard?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

View card for authenticated user.

HTTP Request

GET https://api.bitwage.com/v1/user/viewlinkedcard?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.

Delete Card

>>> import time, requests, json
>>> expiration = int(time.time()+300)
>>> linkedcard_id = <insert Linked Card Id here>
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/user/deletelinkedcard?expire=" + str(expiration) + "&linkedcard_id=" + str(linkedcard_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,headers=headers)
>>> print r

Delete card for authenticated user.

HTTP Request

GET https://api.bitwage.com/v1/user/deletelinkedcard?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.

View Subscriptions

>>> import time, requests
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/user/view_subscription?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,headers=headers)
>>> print r

View current subscriptions for authenticated user.

HTTP Request

POST https://api.bitwage.com/v1/user/view_subscriptions?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.

Cancel Subscription

>>> import time, requests
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/user/cancel_subscription?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,headers=headers)
>>> print r

{
  "result": "success"
}

Cancel active subscription for authenticated user.

HTTP Request

POST https://api.bitwage.com/v1/user/cancel_subscription?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.

Create Subscription

>>> import time, requests
>>> expiration = int(time.time()+300)
>>> url = "https://api.bitwage.com/v1/user/create_subscription?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,headers=headers)
>>> print r

{
  "success": "subscribed"
}

Create subscription for authenticated user.

HTTP Request

POST https://api.bitwage.com/v1/user/create_subscription?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

{
    "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.

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

{
  "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": "example@example.com",
  "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

{
    'linkedaccounts': [{
      '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.

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

{
  "workers": [
    {
      "email": "buspos@giants.com",
      "user_id": 2885074604081128,
      "role": "admin"
    },
    {
      "email": "madbum@giants.com",
      "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&page=3

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.
page	Number	The page of results to return (ie. pagination parameter).

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

{
  "first_name": "John",
  "last_name": "Smith",
  "email": "example@example.com",
  "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': 'example@example.com','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

{
    "to_invite": [
        {
            "email": "example@example.com",
            "role": "admin"
        }
    ]
}

{
  "invite_log": [
    {
      "email": "example@example.com",
      "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": ["example1@example1.com", "example2@example2.com"]}
>>>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

{
    "emails": [
        "example1@example1.com"
    ]
}

{
  "success": [
    {
      "email": "success@success.com",
      "user_id": 6685030696878080
    }
  ],
  "failure": [
    {
      "email": "failure@failure.com",
      "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

{
  "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": "test@example.com", 
               "user_id": 5677071464398848, 
               "userpayroll_id": 6523493654986752
           }
       ]
    },
    {
      "amount": 1.00,
      "currency": "USD",
      "id": 4234242238028288,
      "time_created": "2015-07-16T02:08:36.923968",
      "userpayrolls": [
           {
               "user_email": "test2@example.com", 
               "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

{
  "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": "test@example.com"
    },
    {
      "amount": 1.00,
      "currency": "USD",
      "user_id": 4234242238028288,
      "email": "test2@example.com"
    }
  ],
  "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": "example@example.com",
    "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

{
  "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": "test3@example.com", 
               "user_id": 5677071364398842, 
               "userpayroll_id": 6523423654986751
           }
       ]
    },
    {
      "amount": 1.00,
      "currency": "USD",
      "id": 4234242238028288,
      "time_created": "2015-07-16T02:08:36.923968",
      "userpayrolls": [
           {
               "user_email": "test3@example.com", 
               "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': 'example@example.com','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

{
    "to_pay": [
        {
            "email": "example@example.com",
            "amount_usd": "10.0"
        }
    ]
}

{
  "payroll_id": 5822463824887808,
  "status":'created' #'created' or 'deleted'
  "suborder_list": [
    {
      "email": "example@example.com",
      "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

{
    "payment_method": "wire"
}

{
  "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

{
    "to_delete": [ 
        "5822463824887809"
    ]
}

{
  "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

{
  "company": {
    "id": "6122080743456768",
    "name": "Hello, Inc."
  }
  "invoices": 
    [
      {
        "id": 5725981679550464, 
        "worker": {
            "id": 6122080743456722,
            "email": "test@example.com"
        },
        "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

{
  "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" "support@example.com": 
  },
  "worker": {
    "id": 5769603078684611,
    "email": "test@example.com"
  },
  "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

{
    "invoice_id": "2384192341092834"
}

{
    "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": "joasdf@gmail.com"
        }],
        "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.

Responses and Errors

Responses

The Public Bitwage API v1.0 uses the following error codes:

200

See examples 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"]}]}

Errors

The Public Bitwage API v1.0 uses the following error codes:

Error Code	Meaning
400	Bad Request – Your request sucks
401	Unauthorized – Your API key is wrong
403	Forbidden – The kitten requested is hidden for administrators only
404	Not Found – The specified kitten could not be found
405	Method Not Allowed – You tried to access a kitten with an invalid method
406	Not Acceptable – You requested a format that isn’t json
410	Gone – The kitten requested has been removed from our servers
418	I’m a teapot
429	Too Many Requests – You’re requesting too many kittens! Slow down!
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Public API Bitwage Payroll

Authentication

API Key + Secret

Headers

Out-of-order Processing

Web Application Flow

Step 1 - Authorization

Step 2 - Requesting an Authorization Code

Step 3 - Exchange Authorization Code for Request Token

Request Body Parameters

Username and Password

Extra Headers for Username and Password Authentication

User-Agent

USER_APP

User: Login

HTTP Request

Query Parameters

Request Body Parameters

User: Two Factor Authentication

HTTP Request

Query Parameters

Request Body Parameters

Tickers

Tickers

HTTP Request

Ticker

HTTP Request

User: Profile

Profile

HTTP Request

Query Parameters

Companies

HTTP Request

Query Parameters

BPI Company View

HTTP Request

Query Parameters

BPI Company Edit

HTTP Request

Query Parameters

Request Body Parameters

BPI Company Add

HTTP Request

Query Parameters

Request Body Parameters

BPI Company Delete

HTTP Request

Query Parameters

Request Body Parameters

Add Card

HTTP Request

Query Parameters

Request Body Parameters

View Card

HTTP Request

Query Parameters

Delete Card

HTTP Request

Query Parameters

View Subscriptions

HTTP Request

Query Parameters

Cancel Subscription

HTTP Request

Query Parameters

Create Subscription

HTTP Request

Query Parameters

Worker: History

Payrolls

HTTP Request

Query Parameters

Employer: Profile

Profile

HTTP Request

Query Parameters

Linked Accounts

HTTP Request

Query Parameters

Employer: Workers