This page defines the API specification for the Taxpayer Refund & Banking Solution (TRBS). It provides a structured reference for developers integrating with the TRBS platform. Topics covered include:
The API is designed to be secure, developer-friendly, and compliant with financial and government data handling standards. The API is modular, consistent in design, and optimized for integration with both cloud and on-premise systems.
https://api.refundo.com/api/trbs/v1
Authorization: Bearer {Base64(clientid:secret)}
| Header | Type | Required | Description |
|---|---|---|---|
Authorization |
string | Yes | Bearer token for authentication. |
Content-Type |
string | Yes | application/json for request payloads. |
To support development, sandbox testing, and simulation workflows, the TRBS API accepts an optional request header: X-TRBS-Mode.
| Header Name | Value | Description |
|---|---|---|
| X-TRBS-Mode | Test | Indicates the request is running in test mode. No real-world actions occur. |
| X-TRBS-Mode | Debug | Enables enhanced logging and trace output. |
Best Practice: Remove the
X-TRBS-Modeheader before promoting integrations to production environments.
When the header X-TRBS-Mode: Test is set:
[TEST MODE] prefix in the statusDescription.responseId is prefixed with test-.GET https://api.refundo.com/api/trbs/v1/taxpayer/12345 HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
X-TRBS-Mode: Test
{
"statusCode": 200,
"statusDescription": "[TEST MODE] Tax Payer record retrieved successfully.",
"responseId": "test-c4f1e678-9012-4567-89ab-1234567890cd",
"data": {
"taxpayerId": 12345,
"firstName": "Test",
"lastName": "User",
"email": "[email protected]"
}
}
All API responses contain the following fields:
| Field | Type | Description |
|---|---|---|
statusCode |
integer | HTTP-like status code representing success or failure. |
statusDescription |
string | A brief description of the response outcome. |
responseId |
string | A unique identifier for debugging and tracing. |
data |
object/array/null | The actual data payload (if applicable). |
Example:
{
"statusCode": 200,
"statusDescription": "Request completed successfully.",
"responseId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"data": {
"exampleField": "exampleValue"
}
}
The TRBS API returns standardized HTTP-style status codes to indicate the result of each request. Below is a reference of commonly used status codes across the platform:
| Status Code | Description |
|---|---|
200 |
OK. The request was successful. |
201 |
Created. A new resource was successfully created. |
204 |
No Content. The request was successful but no content is returned. |
400 |
Bad Request. The request was invalid or malformed. |
401 |
Unauthorized. The request lacks valid authentication credentials. |
403 |
Forbidden. The user does not have permission to perform the action. |
404 |
Not Found. The requested resource does not exist. |
409 |
Conflict. The request could not be completed due to a resource conflict. |
429 |
Too Many Requests. The rate limit has been exceeded. |
500 |
Internal Server Error. A generic error occurred on the server. |
503 |
Service Unavailable. The server is temporarily unable to handle the request. |
| Field | Type | Description |
|---|---|---|
page |
integer | Current page number. |
perPage |
integer | Number of items per page. |
totalItems |
integer | Total number of records available. |
data |
array | Array of items. |
Example:
{
"statusCode": 200,
"statusDescription": "Tax Payers retrieved successfully.",
"responseId": "f7d2c839-75b1-4f12-bc2f-91234abcde99",
"page": 1,
"perPage": 10,
"totalItems": 5,
"data": [
{ "taxpayerId": 12345, "firstName": "John", "email": "[email protected]" },
{ "taxpayerId": 12346, "firstName": "Jane", "email": "[email protected]" }
]
}
| Field | Type | Description |
|---|---|---|
statusCode |
integer | HTTP-style error code. |
statusDescription |
string | Description of the failure. |
responseId |
string | Unique ID for tracing the error. |
error |
object | Error metadata. |
Example:
{
"statusCode": 400,
"statusDescription": "Invalid request parameters.",
"responseId": "c9f4e8b7-1234-5678-9abc-abcdef123456",
"error": {
"code": 400,
"details": "The SSN field is required."
}
}
Example:
{
"statusCode": 429,
"statusDescription": "Too many requests. Please try again later.",
"responseId": "def12345-6789-0abc-def1-234567890abc"
}
responseId allows traceability for debugging and auditing.Each of the following API sections provides full CRUD support (Create, Read, Update, Delete) and related operations for its corresponding domain entity:
| API Entity | Description |
|---|---|
| Bank Accounts | Provides operations for bank accounts. Bank accounts are used to store and manage accounts. |
Each link navigates to a dedicated wiki page with request/response formats, supported methods, and integration examples.
To begin using the TRBS API, you must request access credentials from the platform team.
To obtain credentials, please contact the API provisioning team:
Once approved, you will receive a secure package with credentials and integration guidelines.
Note: All API access is logged and monitored. Credentials must be stored securely.
For any technical questions, integration issues, or API-related bugs, please reach out to the TRBS support team.
Support hours: Monday to Friday, 9AM – 5PM EST
When contacting support, always include your
responseId, API URL, and timestamp of the request if possible.