Managing Tax Payments

Now that you've implemented the Quarterly Tax Payments API, you may find that your user needs the ability to take certain actions to view or manage those payments. The Hurdlr API makes this process easy, reducing how much back-end you need to build to support this seemingly complex functionality.

1. Getting estimated payments

Once you've submitted a quarterly estimated payment to the IRS via the Hurdlr API, you can obtain all those payments (and their statuses) for a given user, by running the following GET request:

curl \
  --request GET \
  --url https://sandbox.hurdlr.com/rest/v5/taxes/estimatedPayments \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \

The response from GET /estimatedPayments contains an array of the user's quarterly estimated payments:

{
  "data": [
    {
      "id": 650986,
      "status": "COMPLETED",
      "period": "Q1",
      "year": "2021",
      "amount": 1022.28,
      "paymentInfoId": 52320,
      "lastUpdatedDate": "2021-04-15T15:37:40.107Z"
    }, {
      "id": 987964,
      "status": "ERROR",
      "errorCode": "INVALID_PERIOD",
      "errorMessage": "The IRS is no longer accepting estimated payments for Q2 2021. Please choose a more recent period and resubmit your payment.",
      "period": "Q2",
      "year": "2021",
      "amount": 1022.28,
      "paymentInfoId": 52320,
      "lastUpdatedDate": "2021-09-01T15:37:40.107Z"
    }
  ],
  "lastUpdatedDate": "2021-10-01T15:37:40.107Z"
}

On each payment object, you may find the following attributes to be of particular interest:

Field	Description	Format
id	Id of the estimated payment	Numeric
status	Status of the payment	Must be one of the following: "PENDING", "COMPLETED", "ERROR"
errorCode	Code representing the error encountered. Only populated if `status="ERROR"`.	Must be one of the following: "INVALID_TAX_FILER_INFO", "INVALID_PAYMENT_INFO", "INSUFFICIENT_FUNDS", "INVALID_PERIOD", "OTHER_ERROR"
errorMessage	String that can be displayed to your user, explaining what the error is and how to resolve it. Only populated if `status="ERROR"`.	Any string (e.g. "The name and social security number that you provided do not match. Please update and resubmit your payment.")
period	Period of the estimated payment	Must be one of the following: "Q1", "Q2", "Q3", "Q4"
year	Year for which the estimated payment was (attempted to be) made	Numeric, with 4 digits (e.g. 2021)
amount	Total value of the payment	Numeric, with 2 decimal places
paymentInfoId	Id of the paymentInfo used to (attempt to) make the payment from	Numeric

The possible values for the status attribute are described below:

Value	Use Case
PENDING	The payment is being processed by Hurdlr. Soon, the status will be updated to either "COMPLETED" or "ERROR". You can subscribe to webhooks to get a real-time update.
COMPLETED	The payment was successfully made to the IRS.
ERROR	There was an error during the submission process. See below for the various types of errors.

When the status="ERROR", you can determine what the error is, and alert your user accordingly, using the table below:

Value	Use Case	errorMessage example
INVALID_TAX_FILER_INFO	The user's tax filer info submission does not match the IRS's records. The errorMessage attribute will be a descriptive as the Hurdlr API is able to be.	"The name and social security number that you provided do not match. Please update and resubmit your payment."
INVALID_PAYMENT_INFO	The payment info that the user submitted was not valid.	"The bank account information provided to make the estimated payment was invalid. Please correct the bank account/routing numbers and resubmit your payment."
INSUFFICIENT_FUNDS	The payment info that the user submitted did not have enough money to complete the payment.	"The bank account used to make the estimated payment did not have enough funds to complete the payment. Please update your payment method, or add more funds to the existing payment method, and resubmit your payment."
INVALID_PERIOD	Estimated payments can no longer be made for the period/year combo (e.g. Q3 2021) that was submitted.	"The IRS is no longer accepting estimated payments for Q3 2021. Please choose a more recent period and resubmit your payment."
OTHER_ERROR	Some other error has occurred. Reach out to [email protected] for a quick diagnosis.	"Something went wrong during your payment submission. Please contact support."

2. Updating payment info

You may need to fetch and/or display payment info to your user, that way they can update that info, especially in the case of an errorCode: "INVALID_PAYMENT_INFO". You can obtain the payment info for a given user, by running the following GET request:

curl \
  --request GET \
  --url https://sandbox.hurdlr.com/rest/v5/taxes/paymentInfos \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \

The response from GET /paymentInfos contains an array of the user's payment methods:

[
  {
    "id": 52320,
    "method": "ACH",
    "mask": "x0123",
    "createdDate": "2021-09-15T17:49:12.000Z",
    "lastUpdatedDate": "2021-09-15T17:49:12.000Z",
  }
]

🚧
Masked account number
For data security purposes, the response does not include the accountNo and routingNo fields that were initially inputted when you added the user's payment info. Instead, a mask field containing the last few characters of the accountNo is used, which is typically enough information for your user to identify the account.

To update an existing payment info, simply POST the updated object to the /paymentInfo endpoint; be sure to include the id attribute:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/taxes/paymentInfo \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentInfo": {
      "id": 52320,
      "method": "ACH",
      "accountNo": "1234567890124",
      "routingNo": "123456789"
    }
  }'

3. Updating tax filer info

You may need to fetch and/or display tax filer info to your user, that way they can update that info, especially in the case of an errorCode: "INVALID_TAX_FILER_INFO". You can obtain the filer info for a given user, by running the following GET request:

curl \
  --request GET \
  --url https://sandbox.hurdlr.com/rest/v5/taxes/userTaxPaymentSetup \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \

The response from GET /userTaxPaymentSetup contains a JSON object, with the user's current tax filer info:

{
  "id": 4240,
  "address1": "1815 Adams Mills Rd NW",
  "address2": "#3",
  "city": "Washington",
  "state": "DC",
  "zip": "20009",
  "phonePersonal": "2025555555",
  "dateOfBirth": "1985-12-15",
  "ssn": "555555555",
  "lastUpdatedDate": "2021-09-15T17:48:12.000Z"
}

To update an existing tax filer info, simply POST the updated object to the /userTaxPaymentSetup:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/taxes/userTaxPaymentSetup \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "userTaxPaymentSetup": {
      "id": 4240,
      "address1": "1815 Adams Mills Rd NW",
      "address2": "#3",
      "city": "Washington",
      "state": "DC",
      "zip": "20009",
      "phonePersonal": "2025555555",
      "dateOfBirth": "1977-02-12",
      "ssn": "555555555"
    }
  }'

4. Receiving webhooks (real-time updates)

You can subscribe to programmatically receive real-time updates via webhook to indicate when the status of an estimated payment changes. Contact us directly at [email protected] to let us know the URI of the server that you would like the webhook updates to be sent to.

Each webhook contains the following JSON payload:

{
  "id": 98741, // useful for debugging purposes
  "entity": "taxes.estimatedPayment",
  "type": "UPDATE",
  "data": {
    "id": 987964,
    "status": "ERROR",
    "errorCode": "INVALID_PERIOD",
    "errorMessage": "The IRS is no longer accepting estimated payments for Q2 2021. Please choose a more recent period and resubmit your payment.",
    "period": "Q2",
    "year": "2021",
    "amount": 1022.28,
    "paymentInfoId": 52320,
    "lastUpdatedDate": "2021-09-01T15:37:40.107Z"
  }
}

The data object contains the estimated payment object that was updated. This webhook is useful so that you can update your user in real time, especially in the case of an error.

5. Resubmitting an estimated tax payment

If you've updated the tax filer or payment info due to an estimated tax payment error, chances are that you need to resubmit the estimated payment. You can simply POST the estimated payment; be sure to include the id attribute:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/taxes/estimatedPayment \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "estimatedPayment": {
      "id": 987964,
      "period": "Q3",
      "year": 2021,
      "amount": 1022.28
    }
  }'

1. Getting estimated payments

2. Updating payment info

🚧Masked account number

3. Updating tax filer info

4. Receiving webhooks (real-time updates)

5. Resubmitting an estimated tax payment

🚧
Masked account number