GuidesAPI ReferenceChangelogAPI PolicyGusto Security
Guides
Start typing to search…

Pay contractors

Set up payments to 1099 workers

Due to their different tax treatments, 1099 contractor payments are handled separately from W-2 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.
📘

Recommended: Contractor Payment Groups

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

We recommend using Contractor Payment Group API calls.

1. (Optional) Preview contractor payment groups

You can use the POST /v1/companies/{company_id}/contractor_payment_groups/preview to validate inputs, determine how fast a payment can be made for a company, and handle any submission blockers.

Key information in the response:

  • The expected_debit_date, which is the date the money will be taken out of the company's account.
  • submission_blockers, an array displaying any blockers preventing contractor payments from being made and options for unblocking

Sample request

curl --request POST \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/contractor_payment_groups/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
          }
     ]
}
'

2. Create payments

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

Sample request

curl --request POST \
     --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"
   }
 ]
}

Sample request

{
  "uuid": "f693e034-d833-46e3-88d4-2c820c383c57",
  "company_uuid": "c54046f7-1be4-4c54-8194-f4842c30c86d",
  "check_date": "2024-05-07",
  "debit_date": "2024-05-01",
  "status": "Unfunded",
  "creation_token": "45ef81bb-ae24-4ad1-b2c6-6e563a4c30ed",
  "contractor_payments": [
    {
      "uuid": "630dc982-f498-4ebc-a6dc-4d76711027ce",
      "contractor_uuid": "{contractor_uuid}",
      "bonus": "0.0",
      "hours": "20.0",
      "hourly_rate": "18.0",
      "may_cancel": false,
      "payment_method": "Direct Deposit",
      "reimbursement": "75.0",
      "status": "Unfunded",
      "wage": "0.0",
      "wage_type": "Hourly",
      "wage_total": "360.0"
    },
    {
      "uuid": "12f51eba-d653-4357-8c05-1f1f8d0fd5e3",
      "contractor_uuid": "{contractor_uuid2}",
      "bonus": "0.0",
      "hours": "0.0",
      "hourly_rate": "0.0",
      "may_cancel": false,
      "payment_method": "Check",
      "reimbursement": "0.0",
      "status": "Unfunded",
      "wage": "350.0",
      "wage_type": "Fixed",
      "wage_total": "350.0"
    }
  ],
  "totals": {
    "amount": "785.0",
    "debit_amount": "785.0",
    "wage_amount": "710.0",
    "reimbursement_amount": "75.0"
  }
}

Single contractor payments

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

Sample request

curl --request POST \
     --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
          }
     ]
}
'

Sample response

{
  "uuid": "04552eb9-7829-4b18-ae96-6983552948df",
  "contractor_uuid": "bc57832c-d8bc-43a7-ae99-3a03380ff037",
  "bonus": "20.0",
  "date": "2020-10-19",
  "hours": "40.0",
  "payment_method": "Direct Deposit",
  "reimbursement": "100.0",
  "status": "Unfunded",
  "hourly_rate": "18.0",
  "may_cancel": true,
  "wage": "0.0",
  "wage_type": "Hourly",
  "wage_total": "740.00"
}

3. Return payment receipts

❗️

Important notice

Providing access to contractor payment receipts is a required step. All partners must implement contractor payment receipts.

Every direct deposit contractor payment that is funded—it is considered funded once the ACH transfer has been initiated—requires that a contractor payment receipt be available.

If the contractor payment is by check, canceled, or reversed, no receipt is returned, and you'll get a 404 Not Found error.

Get a payment receipt for direct deposit payments using the GET v1/contractor_payments/{contractor_payment_uuid}/receipt endpoint.

Sample request

curl --request GET \
     --url https://api.gusto-demo.com/v1/contractor_payments/contractor_payment_uuid/receipt \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {token}'

Sample response

{
  "contractor_payment_uuid": "afccb970-357e-4013-81f5-85dafc74f9b6",
  "name_of_recipient": "Patricia Hamill",
  "totals": {
    "company_debit": "748.34"
  },
  "contractor_payments": [
    {
      "contractor_uuid": "f83d0bd8-7e20-43b9-834c-6d514ef6cb47",
      "contractor_first_name": "Patricia",
      "contractor_last_name": "Hamill",
      "contractor_business_name": "",
      "contractor_type": "Individual",
      "payment_method": "Direct Deposit",
      "wage": "448.34",
      "bonus": "248.00",
      "reimbursement": "100.00"
    }
  ],
  "licensee": {
    "name": "Gusto, Zenpayroll Inc.",
    "address": "525 20th St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94107",
    "phone_number": "4157778888"
  },
  "company_uuid": "c827aa0d-3928-4d5a-ab1f-400641a7d2b8",
  "name_of_sender": "Torp and Sons and Sons",
  "debit_date": "2022-06-02",
  "license": "Your payroll provider partners with Gusto Inc. for payments processing. Gusto Inc. is a licensed money transmitter. Learn more on our license page.",
  "license_uri": "https://gusto.com/about/licenses",
  "right_to_refund": "https://gusto.com/about/licenses",
  "liability_of_licensee": "https://gusto.com/about/licenses"
}

What must be inside a receipt?

If a contractor is paid by direct deposit and the payment has been funded, the receipt must include:

  • A receipt ID (the contractor_payment_uuid)
  • Sender name
  • Recipient name (contractor’s full name if an individual, or business name)
  • ACH debit date (when money leaves the sender)
  • Total ACH debit amount
  • Breakdown of amounts debited for contractor wage, bonus, and reimbursements
    • The contractor_payments response attribute provides detail about these amounts.
  • License info, including text; name ("Gusto"), address, and phone number of the Licensee
  • Link “License”, “Right to Refund”, and “Liability of License”
📘

License information

Processing contractor payments requires a Money Transmitter License (MTL) and the information for the license holder must be displayed on the Payroll Receipt. The licensee for the MTL is Gusto. Text for licensee information and URLs for the links are included in the response object.

What about check payments?

For contractor payments made by check, we recommend including a summary of the payroll for the end user to view the debit date, check date, and any other payroll details. Receipt requests for Contractor Payment Receipts will return a 404 Not Found Response if the payment method is by check.

Retrieve processed payments

You can get processed contractor payment groups using either of the following endpoints:

Single contractor payments

You can also get processed single contractor payments using either of the following endpoints:

  1. Get a specific contractor payment: GET companies/{company_uuid}/contractor_payments/{contractor_payment_uuid}
  2. Get all contractor payments for a company: GET companies/{company_id}/contractor_payments

Cancel contractor payments

If a payment is cancellable, you can cancel it by using one of the following endpoints:

Cancellable criteria

Every contractor payment object includes a boolean value may_cancel. When "may_cancel": false, the contractor payment has already been paid out to the contractor.

When may_cancel is true, a payment can be cancelled because one of the following is true:

  • The request to cancel a "Direct deposit" payment is before the cancellation deadline, which is 4:00 pm PST on the payroll_deadline day
  • The contractor payment is a “Check” or “Historical payment” and can always be cancelled, since no money was sent out via ACH by Gusto
📘

Cancelling a contractor payment group

If you're canceling a contractor payment group, then every single payment in that group must have "may_cancel": true. If any one payment in the group has "may_cancel": false, you cannot cancel the whole group.

Updated 1 day ago