1. Use Case 4: Manage Tax Entities
  2. Filter Tax Entities by TIN

The TIN is sensitive data: Remitian never accepts it in plaintext in a URL. To find a tax entity by TIN, encrypt the TIN with the Remitian public key and send it in encryptedTin. Only Remitian can decrypt it.

​
How It Works

PartyHoldsDoes
YouThe Remitian TIN encryption public key, one per environmentEncrypt the TIN on every request
RemitianThe private key, never sharedDecrypt encryptedTin and match the TIN exactly

The TIN never appears in plaintext in the URL or in request logs. The response does not change: same format, and the TIN in it is returned as for any other list request.

Sequence of Events:

  1. Download the Remitian TIN encryption public key from the Developer Portal (any member of your integrator account). Each environment has its own key
  2. Your system encrypts the TIN, exactly as sent on creation (9 digits, no hyphens or spaces), with the public key
  3. Your system sends the list request with the encrypted value in encryptedTin
  4. Remitian decrypts it and responds with the tax entities of the taxpayer whose TIN matches exactly

​
Encryption Parameters

ParameterValue
KeyRSA 4096, public key in PEM format
PaddingOAEP
OAEP hashSHA-256
MGF1 hashSHA-256
InputThe TIN as UTF-8 bytes
OutputBase64url, without = padding

OAEP is randomized, so encrypting the same TIN twice produces different values. Both are valid; encrypt the TIN on every request.

Java: Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding") uses SHA-1 for MGF1 by default and is rejected. Pass an OAEPParameterSpec with MGF1ParameterSpec.SHA256, as in the example below.

​
Examples

C# (.NET 9):

using var rsa = RSA.Create();
rsa.ImportFromPem(publicKeyPem);

var encryptedTin = Base64Url.EncodeToString(
    rsa.Encrypt(Encoding.UTF8.GetBytes("123456789"), RSAEncryptionPadding.OaepSHA256));

Node.js:

const { publicEncrypt, constants } = require('node:crypto');

const encryptedTin = publicEncrypt(
  { key: publicKeyPem, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' },
  Buffer.from('123456789', 'utf8')
).toString('base64url');

Python (cryptography):

import base64
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

public_key = serialization.load_pem_public_key(public_key_pem.encode())
ciphertext = public_key.encrypt(
    b"123456789",
    padding.OAEP(mgf=padding.MGF1(hashes.SHA256()), algorithm=hashes.SHA256(), label=None),
)
encrypted_tin = base64.urlsafe_b64encode(ciphertext).rstrip(b"=").decode()

Java:

String base64 = publicKeyPem.replaceAll("-----(BEGIN|END) PUBLIC KEY-----", "").replaceAll("\\s", "");
PublicKey publicKey = KeyFactory.getInstance("RSA")
    .generatePublic(new X509EncodedKeySpec(Base64.getDecoder().decode(base64)));

Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPPadding");
cipher.init(Cipher.ENCRYPT_MODE, publicKey,
    new OAEPParameterSpec("SHA-256", "MGF1", MGF1ParameterSpec.SHA256, PSource.PSpecified.DEFAULT));
String encryptedTin = Base64.getUrlEncoder().withoutPadding()
    .encodeToString(cipher.doFinal("123456789".getBytes(StandardCharsets.UTF_8)));

HTTP Request:

GET https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/tax-entities?encryptedTin={encryptedTin}
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

The response has the same format as List Tax Entities; the TIN in the response does not change. No match returns an empty list.

​
Errors

A value that cannot be decoded or decrypted, or a decrypted TIN in an invalid format, returns 400 Bad Request. The response never repeats the value sent:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "TaxEntity.InvalidEncryptedTin": [
      "The encrypted TIN is invalid."
    ]
  }
}

The most common causes are a key from another environment, a padding other than OAEP with SHA-256 and MGF1 with SHA-256, standard base64 instead of base64url, or a TIN with hyphens.

If TIN encryption is not available in the environment, the request returns 404 Not Found:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "TIN encryption is not available in this environment.",
  "status": 404
}

​
Key Rotation

The TIN encryption key does not expire. Remitian replaces it only when needed, and notifies you in advance:

  1. Download the new key from the Developer Portal before the announced date.
  2. Update your systems to encrypt with the new key from that date.

After the change, a TIN encrypted with the old key returns 400 Bad Request.


​
Next Steps

See Use Case 4: Manage Tax Entities for the other filters of the tax entity list and for creating tax entities.