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