Public API Bitwage Payroll

The Production API Entry Point: https://api.bitwage.com/v1

The Production Websites: Team Wages: https://team.bitwage.com, Invoicing: https://worker.bitwage.com The Sandbox API Entry Point: https://api.bitwage.biz/v1

The Sandbox Websites: Team Wages: https://team.bitwage.biz, Invoicing: https://worker.bitwage.biz All requests must include an application/json Content-Type Header

All production requests must go over SSL.

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 + 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 * 1 e6 ). 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.

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

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)

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" : "joeshoe@gmail.com" , "password" : "asjdfioas" }

Response JSON structured like this:

{ "username" : "joeshoe@gmail.com, " uuid ": " d 72 f 22 b 5 -cb 00-4168-8 f 82-50 ca 35956 f 3 d" }

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" : "joeshoe@gmail.com" , "uuid" : "d72f22b5-cb00-4168-8f82-50ca35956f3d" , "access_token" : 939393 , "gcm_address" : "asajdkf839829823f9dsa92399929292" }

Response JSON structured like this:

{ "username" : "joeshoe@gmail.com, " apikey ": " b 47 a 747 c 2 c 654 adba 50 f 41 acd 2939511 ", " apisecret ": " 80 fe 301033 df 46 efb 36355247044 bbcb" }

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.

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

Response JSON structured like this:

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

Response JSON structured like this:

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

Response JSON structured like this:

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

Response JSON structured like this:

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

Response JSON structured like this:

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

Response JSON structured like this:

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

Response JSON structured like this:

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

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.

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

Response JSON structured like this:

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

Response JSON structured like this:

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

Response JSON structured like this:

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

Request Body JSON structured like this:

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

Response JSON structured like this:

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

Request Body JSON structured like this:

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

Response JSON structured like this:

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

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

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

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

Request Body JSON structured like this:

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

Response JSON structured like this:

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

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

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

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