Guides

Configuring Postman to Work with Vertex Payroll Tax

Suggest Edits

Postman is an API platform you can configure to work with Vertex Payroll Tax. It provides access to:

  • An API repository
  • Tools for maintaining your APIs
  • Full-lifecycle governance for APIs
  • Workspaces for organization and collaboration

Before you can use Postman, you need to configure it to work with Vertex Payroll Tax. Here's how.

Creating a new request

  1. On the Scratch Pad screen, click the plus (+) sign to create a new collection.
  2. Select an appropriate collection. For example, type paycheck.
  3. Right-click the collection and select Add Request from the drop-down list.
  4. Enter a descriptive name for the new request. For example, type US Federal.

Configuring the request information

Next, you need to set the URL. Use an appropriate URL for the environment and endpoint you are sending the request to. Here are some examples.

Local development

http\://localhost:8181/payroll/v1.0/paychecks

http\://localhost:8182/location/v1.0/address-cleanse

Trial environment

<https://payroll-test.vertexcloud.com/payroll/v1.0/paychecks>

<https://payroll-test.vertexcloud.com/location/v1.0/address-cleanse>

Production environment

<https://payroll.vertexcloud.com/payroll/v1.0/paychecks>

<https://payroll.vertexcloud.com/location/v1.0/address-cleanse>

After you set the URL, you'll need to select the HTTP method. For Payroll Cloud, select either a GET HTTP method or a POST HTTP method.

Configuring authorization with OAuth

📘

Note: If you are testing against a GeoCoder or payroll instance that is running in on-premise mode with on-premise security, skip this section. If you are running against Vertex's trial environment or Vertex's production environment, fill out all the information on the Authorization tab in Postman.

  1. Make the appropriate selections on the Authorization tab:

    a. In the Type drop-down menu, select OAuth 2.0.

    b. In the Add authorization data to drop-down menu, select Request Headers.

    📘

    Note: If you are configuring the authorization information for the first time, skip the following step for now. You cannot select a token until you create and request it. You will need to return to this step to select a token and send your request after you create the token.

    c. In the Current Token section, in the Token drop-down menu, select an existing token that you already created.

    d. In the Header Prefix text box, type Bearer.

  2. Scroll down to the bottom of the screen until you see the Client Authentication select box. Then make the appropriate selections:

    a. In the Token Name text box, enter a name that describes the token so you remember it later. For example, type Payroll Cloud Prod-Test payroll-calculation-test Token to indicate that it is a token for the trial / prod-test environment and that the scope is the payroll-calculation scope.

    b. In the Grant Type drop-down menu, select Client Credentials.

    c. In the Access Token URL text box, enter https://auth.vertexcloud.com/oauth/token.

    📘

    Note: This URL applies to both the trial / prod-test environment and the production environment.

    d. In the Client ID text box, enter your client ID, which you created on the Security & Credentials page.

    e. In the Client Secret text box, enter your client secret, which you created when you created your client credentials.

    🚧

    Caution: Make sure the client ID and secret you enter have the appropriate subscription feature to request the scope.

    f. In the Scope text box, enter one of the following:

    • If you are requesting a token for the trial / prod-test environment, enter either payroll-calculation-test or payroll-addr-cleanse-test.
    • If you are requesting a token for the production environment, enter either payroll-calculation or payroll-addr-cleanse.

    📘

    Note: For address cleanse requests, always request the payroll-addr-cleanse scope or the payroll-addr-cleanse-test scope. For all other endpoints in GeoCoder and payroll, request either the payroll-calculation scope or the payroll-calculation-test scope.

    g. In the Client Authentication drop-down menu, select Send as Basic Auth Header.

  3. Select the Advanced Options tab.

  4. To set the Audience in the Token Request body, enter a key-value pair. Type Audience in the Key text box and type verx://migration-api in the Value text box.

  5. After everything is configured, click the Get New Access Token button. This makes the token request with your client credentials. A success message displays.

  6. Click the Proceed button.

  7. On the following page, click the Use Token button. The value of the token string displays in the Token text box.

Configuring the request body

  1. Click on the Request Body tab.

  2. Select the raw radio button.

  3. Select either the XML or JSON content type.

  4. Paste an XML or JSON request into the text area for the body.

    🚧

    Caution: Make sure the content type and the request body content you paste match.

  5. Click the Send button. An HTTP 220 status code and a response back from the endpoint display.

Requesting a token programmatically

Make an HTTP POST request to https://auth.vertexcloud.com/oauth/token. Here is how to structure HTTP POST request headers:

  1. Build the authorization header: client_id.client_secret.
  2. Use your client ID and secret to build the client_id.client_secret string. The client_id.client_secret string is base64 encoded and placed in the Authorization header as:
    Authorization: Basic <base64_encoded(client_id.client_secret)>

Token request headers example

Content-Type: application/x-www-form-urlencoded

Authorization: Basic <your_base64_encoded_client_id_dot_client_secret_string>

Accept: */*

Cache-Control: no-cache

Host: auth.vertexcloud.com

Accept-Encoding: gzip, deflate, br

Connection: keep-alive

Token request body example

grant_type=client_credentials&scope=payroll-calculation-test&audience=verx%3A%2F%2Fmigration-api

Notes:

  • If you request a token to use address cleanse, then you need to request a token with the payroll-addr-cleanse scope. For all other payroll and GeoCoder endpoints, request a token with the payroll-calculation scope.
  • If you are requesting to the trial environment instead of the production environment, add -test to the end of the requested scope name or names.

Token response headers example

HTTP/1.1 200 OK

Date: Wed, 06 Sep 2023 17:17:44 GMT

Content-Type: application/json

Transfer-Encoding: chunked

Connection: keep-alive

Cache-Control: no-store

Pragma: no-cache

Content-Encoding: br

Token response body example

The access token is what you put into your request to the payroll or GeoCoder endpoints in the Authorization header.

{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik1FUkJOelV6UmpORlFUTkRSa1ZDTURReE56TTVNRVZET1RoRU5EZ3pNRVpHTmpjM05VSXpNdyJ9.eyJpc3MiOiJodHRwczovL2F1dGgudmVydGV4Y2xvdWQuY29tLyIsInN1YiI6Ikd3MFQ1eEo1aFVCRmo0WHcybFJuMXZTcXdQcjllMlZjQGNsaWVudHMiLCJhdWQiOiJ2ZXJ4Oi8vcGF5cm9sb","scope":"vtms-internal-api payroll-calculation-test","expires_in":86400,"token_type":"Bearer"}

Paychecks request example

Make an HTTP POST to the appropriate environment's paycheck endpoint:

Local Payroll Dev: http://localhost:8181/payroll/v1.0/paychecks

Payroll Trial: https://payroll-test.vertexcloud.com/payroll/v1.0/paychecks

Payroll Prod: https://payroll.vertexcloud.com/payroll/v1.0/paychecks

Paychecks request headers example

Content-Type: application/json

Authorization: Bearer <your_access_token_string_from_the_token_response_body>

Accept: */*

Cache-Control: no-cache

Host: payroll-test.vertexcloud.com

Accept-Encoding: gzip, deflate, br

Connection: keep-alive

If you are using the XML endpoints, make sure Content-Type has a value of application/xml.

Paychecks request body example

{

"employee": {

"employeeId": "334455",

"payPeriod": {

"payDate": "2023-01-15",

"totalPeriods": 26,

"currentPeriod": 1

},

"defaultSupplementalPayTypeTreatment": "Regular",

"residenceGeocodeId": "181930360",

"primaryWorkGeocodeId": "180251296",

"specialPayPeriod": "NotSpecial",

"periodToDateAggregation": false

},

"workLocations": [

{

"compensations": [

{

"amount": 2000,

"compensationCodeId": "0",

"payType": "Regular"

}

],

"geocodeId": "180251296",

"workLocationId": "Work Location 1"

}

],

"jurisdictions": [],

"calculationOverrides": [],

"deductions": [],

"formsData": [],

"aggregatedCompensations": [],

"options": {},

"deductionOverrides": [],

"canadianDetails": [],

"aggregatedTaxes": [],

"compensationOverrides": []

}

The contents of the request body must be a valid JSON or XML request for the requested endpoint.

Paychecks response headers example

Date: Wed, 06 Sep 2023 17:17:52 GMT

Content-Type: application/json

Transfer-Encoding: chunked

Connection: keep-alive

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

Paychecks response body example

Here is a snippet of the paychecks JSON response. The full response is lengthy, so only the first part of it is included here.

"employeeId": "334455",

"taxResults": [

{

"taxRecordIdentifier": {

"taxIdentifierId": "400",

"geocodeId": "000000000"

},

"taxName": "FEDERAL WH",

"taxType": "FederalTax",

"calculationStatus": "OK",

"taxAmount": 167.62,

"supplementalPayTaxAmount": 0.00,

"adjustedGross": 2000.00,

"adjustedSupplementalGross": 0.00,

"annualizedAdjustedCurrentGross": 43400.00,

"annualizedAdjustedSupplementalGross": 0.00,

"annualizedRegularTax": 4358.00,

"annualizedSupplementalTax": 0.00,

"subjectGrossAmount": 2000.00,

"taxableGross": 2000.00,

"taxableTips": 0.00,

"utilizedAlternativeCalculationCode": 99,

"utilizedBaseAmount": 0.00,

"calculationMethod": "Annualize",

"utilizedExemptAmount": 0.00,

"filingStatusId": "62",

"utilizedRate": 0.120000,

"utilizedSupplementalRate": 0.000000,

"recalculation": "No",

"utilizedSupplementalPayTypeTreatment": "Regular"

},

📘

Note: Make sure an HTTP Status of 200 is returned along with the JSON or XML response for the requested endpoint.

JSON example snippets

View snippets of example JSON files here or access the full JSON example scripts here.

Updated 3 months ago