TRN Validate SPI
Overview
The Tax Registration Number Validate Service Provider Interface (SPI) is a robust solution designed to facilitate seamless communication between Chargebee and external API platforms offering essential tax-related services. This SPI enables Chargebee, a leading SaaS platform managing subscriptions and revenue operations, to efficiently validate tax registration numbers for merchants, offering both individual and batch validation capabilities.
This detailed overview provides comprehensive insights for third-party users seeking to integrate their API platforms with Chargebee's Tax Registration Number Validation Service, ensuring a smooth and secure validation process for merchants within the Chargebee ecosystem.
Key Services Provided
Individual Tax Registration Number Validation: Ensures the accuracy and legitimacy of tax registration numbers on a one-by-one basis.
Batch Tax Registration Number Validation: Streamlines the validation process for merchants dealing with large datasets by allowing bulk validation.
Integration
If you operate an API platform that provides the aforementioned tax-related services, you can leverage this specification to build an adapter service. This adapter service will act as the intermediary between Chargebee and your API, enabling seamless integration of your services into the Chargebee ecosystem.
The Service Adapter performs the following key functions:
Request Translation: Translates API requests from Chargebee into the format specified by the Service Provider's API.
Response Translation: Converts API responses from the Service Provider's APIs into a format understood by Chargebee.
Authorization Process
Chargebee employs HTTP header-based authorization for all API endpoints associated with the Service Adapter. The authorization key is dynamically passed in the HTTP header. The parameter containing this key is specified in the JSON object api_configuration, a requisite for configuring onboarding on Chargebee's marketplace. Within the api_configuration object, the Taxes Service Adapter SPI checks the authorization key parameter from credential_configuration.id and generates the HTTP header-based input query parameter for authorization. The credential_configuration is an array of objects, each with an id attribute, and the value of id corresponds to the parameter containing the authorization key.
For detailed JSON snippets and configuration examples, refer to the Taxes Service Adapter SPI documentation.
SPI Capabilities
This section outlines the primary functions of the TRN SPI and the scenarios in which Chargebee employs them.
Health check
GET /health
Required
Implementing this endpoint is a necessity for successful integration with Chargebee.
The /health endpoint supplies real-time updates about the operational health of the Tax Service Provider. Chargebee employs this endpoint to monitor the condition of the tax provider system. It assesses the overall service health as well as the status of individual components such as the Tax Adapter API server, Tax API server, and the application database.
Authenticating Chargebee calls
POST /credentials/validate
This endpoint is called when the merchant connects their Chargebee site to the tax service adapter.
TRN Validate
POST /trn/validate
The /validate endpoint is used to validate individual tax registration details. By submitting tax registration information, including parameters such as TRN (Tax Registration Number), country, name, and additional codes, users can validate their TRN.
GET /trn/validate/{requestId}
This endpoint is used to obtain the detailed response of a tax registration number validation request. By providing the unique Request ID associated with a previous validation request, users can retrieve information such as the country, name, code, and status (trnStatus) of each validated tax registration number.
POST /trn/validate/batch
This endpoint is used for validating tax registration numbers in bulk. It facilitates the submission of an array of tax registration numbers, each accompanied by pertinent parameters such as TRN (Tax Registration Number), country, and code.
GET /trn/validate/batch/{batchId}
This endpoint serves the purpose of retrieving tax registration numbers in batches, providing comprehensive details such as batchId, batchName, status, and individual Tax Registration Numbers (TRNs) within the response.
DELETE /trn/validate/batch/{batchId}
This endpoint is designed to facilitate the cancellation of a running batch of tax registration number validation requests on the server side. By providing the batch ID as a parameter, users can effectively terminate the ongoing validation process for a specific set of tax registration numbers.
Terminology
To facilitate a clear understanding, let's define key terms used in this specification:
Merchant (Seller): Refers to Chargebee's customer engaged in the business of selling products. Merchants may have one or more Chargebee accounts.
Chargebee: The SaaS platform responsible for managing subscriptions and revenue operations on behalf of the Merchant. Chargebee initiates API calls to the Tax Service Adapter for tax estimation and filing transactions between the Merchant and the Customer.
Customer: Represents the Merchant's customer who purchases products. Customer records and associated details are stored within Chargebee under the Merchant’s account.
Service Provider: Denotes the external service entity that provides services tailored for merchants.
Service Adapter (SPI): The SPI, as defined in this document, serves the critical role of translating API requests and responses between Chargebee and the Service Provider's API.