Contractor Payments
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:
- Direct deposit - Gusto will deposit the funds to the bank account associated with the contractor.
- 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.
- 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.
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 <<COMPANY_API_TOKEN>>' \
--header 'content-type: application/json' \
--data '
{
"contractor_payments": [
{
"bonus": 550,
"contractor_uuid": "{contractor_uuid}",
"date": "2021-05-17",
"hourly_rate": 25,
"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 the 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 <<COMPANY_API_TOKEN>>' \
--header 'content-type: application/json' \
--data '
{
"contractor_payments": [
{
"bonus": 550,
"contractor_uuid": "{contractor_uuid}",
"date": "2021-05-17",
"hourly_rate": 25,
"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));
3. Retrieve Processed Payments
Once created you can get processed payments using:
GET companies/{company_uuid}/contractor_payments/{contractor_payment_uuid}
endpoint for specific Payment IDsGET companies/{company_id}/contractor_payments
endpoint at the Company level
Note that all contractor payments are done on a contractor-by-contractor basis and there is not a bulk payment that includes multiple contractors at once.
Cancel a Payment
Each contractor payment will include the boolean
may_cancel
. If set totrue
, using the specific payment ID, send a delete request to theDELETE companies/{company_id}/contractor_payments/{contractor_payment_id}
endpoint. If it is set tofalse
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
.
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 3 months ago