- Use Case 4: Manage Tax Entities
- Filter Tax Entities by TIN
Use Case 4: Manage Tax Entities
Filter Tax Entities by TIN
Find a tax entity by its TIN without sending the TIN in plaintext, using the encryptedTin filter.
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
| Party | Holds | Does |
|---|---|---|
| You | The Remitian TIN encryption public key, one per environment | Encrypt the TIN on every request |
| Remitian | The private key, never shared | Decrypt 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:
- Download the Remitian TIN encryption public key from the Developer Portal (any member of your integrator account). Each environment has its own key
- Your system encrypts the TIN, exactly as sent on creation (9 digits, no hyphens or spaces), with the public key
- Your system sends the list request with the encrypted value in
encryptedTin - Remitian decrypts it and responds with the tax entities of the taxpayer whose TIN matches exactly
Encryption Parameters
| Parameter | Value |
|---|---|
| Key | RSA 4096, public key in PEM format |
| Padding | OAEP |
| OAEP hash | SHA-256 |
| MGF1 hash | SHA-256 |
| Input | The TIN as UTF-8 bytes |
| Output | Base64url, 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:
- Download the new key from the Developer Portal before the announced date.
- 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.