GuidesAPI ReferenceChangelogAPI PolicyAPI StatusGusto Security
Guides
These docs are for v2023-09-01. Click to read the latest docs for v2024-04-01.

Contractor Payments

Suggest Edits

Due to their different tax treatments, 1099 Contractor payments are handled separately from W2 Employee payroll and off-cycle payroll.

Contractors can have three types of payment methods:

  1. Direct deposit - Gusto will deposit the funds to the bank account associated with the contractor.
  2. Check - the payroll admin will be responsible for providing the contractor with a check for the amount of the payment. The amount will be reported on the 1099 of the contractor.
  3. Historical payment - the contractor was already paid and the amount is being added for reporting purposes only. When using the historical payment method, the date of the payment must be in the past. The contractor will not receive any compensation for this payment as it is exclusively for reporting purposes.

Contractor payment actions can be made through single Contractor Payment API calls or through Contractor Payment Group API Calls

1. Preview Contractor Payment Dates (Optional)

You can use the GET companies/{company_uuid}/contractor_payments/preview endpoint determine the payment speed a payment can be paid out for a given company. This will return the expected_debit_date for the payment.

curl --request GET \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/contractor_payments/preview \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token' \
     --header 'content-type: application/json' \
     --data '
{
     "contractor_payments": [
          {
               "bonus": 550,
               "contractor_uuid": "{contractor_uuid}",
               "date": "2021-05-17",
               "hours": 15,
               "payment_method": "Direct Deposit",
               "reimbursement": 20
          }
     ]
}
'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/companies/{company_uuid}/contractor_payments/preview';
const options = {
  method: 'GET',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    contractor_payments: [
      {
        bonus: 550,
        contractor_uuid: '{contractor_uuid}',
        date: '2021-05-17',
        hourly_rate: 25,
        hours: 15,
        payment_method: 'Direct Deposit',
        reimbursement: 20
      }
    ]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

2. Create Contractor Payment

You can create a single contractor payment using the POST companies/{company_id}/contractor_payments endpoint. 

curl --request GET \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/contractor_payments/ \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token' \
     --header 'content-type: application/json' \
     --data '
{
     "contractor_payments": [
          {
               "bonus": 550,
               "contractor_uuid": "{contractor_uuid}",
               "date": "2024-07-17",
               "hours": 15,
               "payment_method": "Direct Deposit",
               "reimbursement": 20
          }
     ]
}
'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/companies/{company_uuid}/contractor_payments/';
const options = {
  method: 'GET',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    contractor_payments: [
      {
        bonus: 550,
        contractor_uuid: '{contractor_uuid}',
        date: '2021-05-17',
        hourly_rate: 25,
        hours: 15,
        payment_method: 'Direct Deposit',
        reimbursement: 20
      }
    ]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

You can create contractor group with multiple contractor payments using the POST companies/{company_id}/contractor_payment_groups endpoint.

curl --request GET \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/contractor_payment_groups/ \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token' \
     --header 'content-type: application/json' \
     --data '
{
 "check_date": "2024-08-06",
 "contractor_payments": [
   {
     "contractor_uuid": "{contractor_uuid}",
     "payment_method": "Direct Deposit",
     "hours": "20"
   },
   {
     "contractor_uuid": "{contractor_uuid2}",
     "payment_method": "Check",
     "wage": "350"
   }
 ]
}

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/companies/{company_uuid}/contractor_payments/';
const options = {
  method: 'GET',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    contractor_payments: [
      {
        bonus: 550,
        contractor_uuid: '{contractor_uuid}',
        date: '2021-05-17',
        hourly_rate: 25,
        hours: 15,
        payment_method: 'Direct Deposit',
        reimbursement: 20
      }
    ]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

3. Retrieve Processed Payments

Once created you can get processed single contractor payments using:

  1. GET companies/{company_uuid}/contractor_payments/{contractor_payment_uuid} endpoint for specific Payment IDs
  2. GET companies/{company_id}/contractor_payments endpoint at the Company level

Once created you can get processed contractor payment groups using:

  1. GET contractor_payment_groups/{contractor_payment_group_uuid} endpoint for specific Contractor Payment Group IDs
  2. GET companies/{company_id}/contractor_payment_groups endpoint at the Company level

📘

Cancel a Contractor Payment

Each contractor payment will include the boolean may_cancel. If set to true, using the specific payment ID, send a delete request to the DELETE companies/{company_id}/contractor_payments/{contractor_payment_id} endpoint. If it is set to false the contractor payment has already been paid out to the contractor. “Check” and “historical payment” contractor payments can always be canceled given no money was sent out via ACH by Gusto.

A payment cannot be canceled after 3:30pm PST on the payroll_deadline.

📘

Cancel a Contractor Payment Group

Each contractor payment will include the boolean may_cancel. If for all individual contractor payments within a group, may_cancelis set to true, using the specific payment group ID, send a delete request to the DELETE contractor_payment_groups/{contractor_payment_group_uuid} endpoint. If any of the contractor_payments within the group have "may_cancel":false, the contractor payment has already been paid out to the contractor and the group cannot be canceled. “Check” and “historical payment” contractor payments can always be canceled given no money was sent out via ACH by Gusto.

A payment cannot be canceled after 3:30pm PST on the payroll_deadline.

4. Return Payment Receipt

Once a payroll is submitted, we recommend including a summary of the payroll for the end user to view the debit date, check date, and payroll details. The payroll receipt should also be available on this final step. See Contractor Payment Receipts for more information.

You can retrieve a Payment Receipt using the GET contractor_payments/{contractor_payment_uuid}/receipt endpoint.

Updated 4 months ago