Introduction

Our Document Downloads feature provides an easy way for you to download an end-user's original paystub. The document will be provided as an additional field in the /paystubs endpoint and there is no additional cost if you're already leveraging the JSON data making the implementation very straightforward.

Implementation

Step 1: Subscribe to the webhook event for paystubs documents

Subscribe to the paystubs.documents.added webhook using the request below

POST /v1/webhooks
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "url": "https://your-domain.com/webhook_endpoint",
  "status": "ACTIVE",
  "enabled_events": [
    "paystubs.documents.added",
  ]
}

This webhook will be published when the document is ready to be downloaded. You will get a paystub.documents.added webhook for each unique paystub.

NOTE: if you are subscribed to the paystubs.added event as well, that webhook will be published before the paystubs.documents.added event due to the additional processing needed for the document. If you call the /paystubs endpoint before receiving the paystubs.documents.added webhook, then the document object will be returned null but the JSON data will still be available.

{
  "event": "paystubs.documents.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "31de723f-a893-42a5-adca-a727f11ad792",
    "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",
    "end_user_id": "my_user_12345",
    "link_token_id": "7c4ac4be-4a0e-4468-ab26-c42b249b233b",
    "name": "paystubs_documents",
    "timestamp": "2021-01-21T20:16:28+00:00",
    "outcome": "success",
    "error_code": null,
    "params": {
      "from_pay_date": "2020-10-01",
      "to_pay_date": "2020-12-31",
      "count": 6,
      "sync_status": "in_progress",
    }
  }
}

Note: The end_user_id is your internal reference to the end user. See User Model for more information.

Step 2: Retrieve the document

The document download_url can be retrieved using the same /paystubs endpoint that you use for the JSON data. The majority of documents will be returned in a PDF formant.

For security purposes, the download_url is only active for 15 minutes. As such, we recommend that you download the document as soon as you retrieve the download_url. If the download_url has expired, calling the /paystubs endpoint again will generate a new, active download_url.

Request

GET /v1/accounts/03bbc20e-bc39-464a-b4dc-4b63ffb7213d/paystubs?limit=1
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET

Response

See the full Paystubs API reference here.

{
  "meta": {
    "count": 1
  },
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",
      "pay_date": "2020-12-31",
      "pay_period_start": "2020-12-10",
      "pay_period_end": "2020-12-24",
      "currency": "usd",
      "gross_pay_amount": 480769,
      "net_pay_amount": 273563,
      "check_amount": 280563,
      "gross_pay_ytd": 6971151,
      "net_pay_ytd": 4357992,
      "total_taxes": 139680,
      "total_deductions": 66704,
      "total_reimbursements": 7000,
      "taxes": [
        {
          "name": "Federal Income Tax",
          "category": "federal_income",
          "amount": 65158
        },
        {
          "name": "Social Security",
          "category": "social_security",
          "amount": 29249
        },
        {
          "name": "Medicare",
          "category": "medicare",
          "amount": 6840
        },
        {
          "name": "New York Income Tax",
          "category": "state",
          "amount": 22860
        },
        {
          "name": "New York City Income Tax (New York County)",
          "category": "local",
          "amount": 15573
        }
      ],
      "document": {
          "id": "aea8cc55-93fa-452d-8eac-b83c80b19a41",
          "download_url": [document download URL],
          "download_url_expiration": "2022-04-04T18:13:55.123450+00:00",
      },
      "deductions": [
        {
          "name": "Aetna PPO",
          "category": "medical_insurance",
          "amount": 7012,
          "type": "pre_tax"
        },
        {
          "name": "401(k) deferral",
          "category": "retirement",
          "amount": 57692,
          "type": "pre_tax"
        },
        {
          "name": "Transit",
          "category": "commuter",
          "amount": 2000,
          "type": "pre_tax"
        }
      ],
      "earnings": [
        {
          "name": "Regular Earnings",
          "category": "salary",
          "amount": 480769,
          "rate": null,
          "hours": null
        }
      ],
      "created_at": "2022-01-10T19:54:45.745660+00:00"
    }
  ]
}