Tax Payer

Retrievs a Taxpayer - v2.0

get

This endpoint retrieves the taxpayer's details associated with a specific merchant. It provides detailed information such as the taxpayer's Legal First Name, Legal Last Name, TIN Type ID, and other relevant attributes stored in the database. The endpoint also supports an optional parameter, encryptedTin, which can be set to true if encrypted TIN values are required in the response. Clients using this endpoint should ensure they have the necessary entitlements and pass a valid merchant number in the request. This is critical for retrieving taxpayer information securely and accurately.

Path parameters
merchantNumberstringRequired

Merchant number used to get tax payer details.

Query parameters
encryptedTinbooleanOptionalDefault: false
Header parameters
exchangeIdstringOptional

Correlation Id for the request

Responses
200
Returns a Taxpayer's details successfully.
application/json
get
GET /api/demographics/v2/Taxpayers/{merchantNumber} HTTP/1.1
Host: localhost:5000
Accept: */*
{
  "legalFirstName": "John",
  "legalLastName": "Doe",
  "tin": "123456789",
  "encryptedTIN": "[****3433, ****4485]",
  "tinLastFour": "4673",
  "tinTypeID": 2,
  "businessLegalName": "Acme Corporation",
  "stateIncorporatedCode": "CA"
}

Updates a Taxpayer - v2.0

put

This endpoint allows to update a taxpayer's details associated with a specific merchant, identified by the merchantNumber. The request body contains the taxpayer's details, including fields such as legalFirstName, legalLastName, tinTypeId, and other relevant attributes. Clients should ensure that all required fields in the request body are properly filled and valid before making the request. The endpoint supports an optional encryptedTin parameter, which, when set to true, ensures that TIN values are stored and transmitted in an encrypted format for added security.

Path parameters
merchantNumberstringRequired

Merchant number used to update the tax payer's details.

Query parameters
encryptedTinbooleanOptionalDefault: false
Header parameters
exchangeIdstringOptional

Correlation Id for the request

Body
legalFirstNamestring | nullableOptional

First name of the tax payer.

Example: John
legalLastNamestring | nullableOptional

Last name of the tax payer.

Example: Doe
tinstring · min: 9 · max: 9Required

Taxpayer Identification Number (TIN). Must be exactly 9 characters long.

Example: 123456789
encryptedTINstring · byte | nullableOptional

Encrypted representation of the TIN for security purposes.

Example: [****3433, ****4485]
tinLastFourstring | nullableRead-onlyOptional

Represents last fout digits of TIN number

Example: 4673
tinTypeIDinteger · int32 · min: 1 · max: 3Required

Identifier for the type of TIN. Must be between 1 and 3.

Example: 2
businessLegalNamestringRequired

The legal name of the business associated with the taxpayer.

Example: Acme Corporation
stateIncorporatedCodestring | nullableOptional

The state where the business is incorporated. Represented as a two-character code.

Example: CA
Responses
200
Saves a Taxpayer successfully.
application/json
put
PUT /api/demographics/v2/Taxpayers/{merchantNumber} HTTP/1.1
Host: localhost:5000
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 185

{
  "legalFirstName": "John",
  "legalLastName": "Doe",
  "tin": "123456789",
  "encryptedTIN": "[****3433, ****4485]",
  "tinTypeID": 2,
  "businessLegalName": "Acme Corporation",
  "stateIncorporatedCode": "CA"
}
{
  "legalFirstName": "John",
  "legalLastName": "Doe",
  "tin": "123456789",
  "encryptedTIN": "[****3433, ****4485]",
  "tinLastFour": "4673",
  "tinTypeID": 2,
  "businessLegalName": "Acme Corporation",
  "stateIncorporatedCode": "CA"
}

Was this helpful?