Configuring Postman to Work with Vertex Payroll Tax
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
- On the Scratch Pad screen, click the plus (+) sign to create a new collection.
- Select an appropriate collection. For example, type
paycheck
. - Right-click the collection and select Add Request from the drop-down list.
- 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.
-
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
. -
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
orpayroll-addr-cleanse-test
. - If you are requesting a token for the production environment, enter either
payroll-calculation
orpayroll-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.
- If you are requesting a token for the trial / prod-test environment, enter either
-
Select the Advanced Options tab.
-
To set the Audience in the Token Request body, enter a key-value pair. Type
Audience
in the Key text box and typeverx://migration-api
in the Value text box. -
After everything is configured, click the Get New Access Token button. This makes the token request with your client credentials. A success message displays.
-
Click the Proceed button.
-
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
-
Click on the Request Body tab.
-
Select the raw radio button.
-
Select either the XML or JSON content type.
-
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.
-
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:
- Build the authorization header:
client_id.client_secret
. - 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 thepayroll-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 4 months ago