---
updatedAt: 2026-02-12T18:31:50.000Z
agentTools:
projectIndex: https://developers.bizapis.com/llms.txt
---
# SS-PAYREF-TSU (Segurança Social Referencia de Pagamento TSU)
Retrieve payment references for TSU
# What's New in bizAPIs 3.0
**Enhanced Error Responses with bizAPIs Status Codes**
bizAPIs 3.0 introduces structured error responses with dedicated bizAPIs status codes, making debugging faster and support interactions more efficient. All error responses now include detailed metadata like `requestId`, `errorCode`, and `errorName` to help you quickly identify and resolve issues.
### Availability by Environment
| Environment | Status |
| -------------------- | ------------- |
| 📚 **Documentation** | ⏳ Coming Soon |
| 🧪 **QUAL** | ⏳ Coming Soon |
| 🚀 **Production** | ⏳ Coming Soon |
[Learn more about error handling →](#error-handling)
> ⚠️ Important Notice
>
> The option to receive the pdf document associated with the extracted information is only available for licenses that include access to this file.\
> If you wish to enable this feature in your plan, please contact our sales team for further details and subscription options.
# JSON Schema for API Response
```json ENG
{
"type" : "object",
"properties" : {
"message" : {
"type" : "string",
"description" : "A human-readable message providing additional information about the response, such as error details or informative status updates"
},
"data" : {
"type" : "object",
"properties" : {
"requestId" : {
"type" : "string",
"description" : "Unique identifier for the request"
},
"paymentDocs" : {
"type" : "array",
"description" : "List of TSU payment documents",
"items" : {
"type" : "object",
"properties" : {
"documentId" : {
"type" : "string",
"description" : "Unique identifier for the document"
},
"emissionDate" : {
"type" : "string",
"description" : "Document emission date"
},
"validityDate" : {
"type" : "string",
"description" : "Document validity date"
},
"emittedBy" : {
"type" : "string",
"description" : "Name of the entity that emitted the document"
},
"niss" : {
"type" : "string",
"description" : "Emitting entity NISS"
},
"nif" : {
"type" : "string",
"description" : "Emitting entity NIF"
},
"amount" : {
"type" : "number",
"description" : "Amount to Pay"
},
"iban" : {
"type" : "string",
"description" : "IBAN receiving entity"
},
"swift" : {
"type" : "string",
"description" : "SWIFT receiving entity"
},
"entity" : {
"type" : "string",
"description" : "Receiving entity"
},
"paymentReference" : {
"type" : "string",
"description" : "Payment reference associated with the payment document"
}
}
}
}
}
},
"files" : {
"type" : "array",
"description" : "A list of files, each encoded as a Base64 string. Used when multiple files are included in the response.",
"items" : {
"type" : "string"
}
}
}
}
```
```json PT
{
"type" : "object",
"properties" : {
"message" : {
"type" : "string",
"description" : "Mensagem legível para humanos que fornece informações adicionais sobre a resposta, como detalhes de erro ou atualizações informativas de estado"
},
"data" : {
"type" : "object",
"properties" : {
"requestId" : {
"type" : "string",
"description" : "Identificador único do pedido"
},
"paymentDocs" : {
"type" : "array",
"description" : "Lista de documentos de pagamento TSU",
"items" : {
"type" : "object",
"properties" : {
"documentId" : {
"type" : "string",
"description" : "Identificador único do documento"
},
"emissionDate" : {
"type" : "string",
"description" : "Data de emissão do documento"
},
"validityDate" : {
"type" : "string",
"description" : "Data de validade do documento"
},
"emittedBy" : {
"type" : "string",
"description" : "Nome da entidade que emitiu o documento"
},
"niss" : {
"type" : "string",
"description" : "NISS da entidade emissora"
},
"nif" : {
"type" : "string",
"description" : "NIF da entidade emissora"
},
"amount" : {
"type" : "number",
"description" : "Montante a pagar"
},
"iban" : {
"type" : "string",
"description" : "IBAN da entidade recebedora"
},
"swift" : {
"type" : "string",
"description" : "SWIFT da entidade recebedora"
},
"entity" : {
"type" : "string",
"description" : "Entidade recebedora"
},
"paymentReference" : {
"type" : "string",
"description" : "Referência de pagamento associada ao documento de pagamento"
}
}
}
}
}
},
"files" : {
"type" : "array",
"description" : "Lista de ficheiros, cada um codificado como uma string Base64. Utilizado quando múltiplos ficheiros estão incluídos na resposta.",
"items" : {
"type" : "string"
}
```
#### Best Practices
* **Always log the `requestId`** - Include it when contacting support for faster issue resolution
* **Use `errorCode` or `errorName`** for programmatic error handling in your application
* **Reference the timestamp** for correlating errors with your application logs
📖 **View complete error codes reference →**
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "bizapis",
"version": "2"
},
"servers": [
{
"url": "https://apigwws.bizapis.com/v2/documents/"
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "apiKey",
"in": "header",
"x-default": "eyJuYW1lIjoiRG9jdW1lbnRhdGlvbiIsImxpY2Vuc2UiOiJiM2ZkZDQzYS1kMDNhLTQwMTctODRmNS1jZTc2ZmI3YzEwNDAiLCJ0eXBlIjowfQ",
"name": "Authorization",
"x-bearer-format": "bearer"
}
}
},
"security": [
{
"sec0": []
}
],
"paths": {
"/ss-payref-tsu": {
"post": {
"summary": "SS-PAYREF-TSU (Segurança Social Referencia de Pagamento TSU)",
"description": "Retrieve payment references for TSU",
"operationId": "ss-payref-tsu-segurança-social-referencia-de-pagamento-tsu",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"user",
"password"
],
"properties": {
"user": {
"type": "string",
"description": "Taxpayer number",
"default": "test"
},
"password": {
"type": "string",
"description": "Social Security access password",
"default": "test"
},
"includeDocument": {
"type": "boolean",
"description": "Flag to indicate whether to include the pdf document on the response",
"default": "false"
}
}
},
"examples": {
"request": {
"value": {
"user": "test",
"password": "test"
}
},
"Loading problem reaching authentication": {
"value": {
"user": "",
"password": "reachAuthentication"
}
},
"Loading page timeout": {
"value": {
"user": "",
"password": "pageTimeout"
}
},
"Failed extract data": {
"value": {
"user": "",
"password": "extractData"
}
},
"Invalid credentials": {
"value": {
"user": "",
"password": "invalidCredentials"
}
},
"Login Timeout": {
"value": {
"user": "",
"password": "loginTimeout"
}
},
"No access": {
"value": {
"user": "",
"password": "nopermission"
}
},
"No data found": {
"value": {
"user": "",
"password": "nodatafound"
}
},
"Recovery required": {
"value": {
"user": "",
"password": "recoveryrequired"
}
},
"Error in authentication": {
"value": {
"user": "",
"password": "errorauthentication"
}
}
}
}
}
},
"responses": {
"200": {
"description": "200",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"data\": {\n \"paymentDocs\": [\n {\n \"documentId\": \"DOC123456\",\n \"emissionDate\": \"2024-06-01\",\n \"validityDate\": \"2024-07-01\",\n \"emittedBy\": \"Mock Authority\",\n \"niss\": \"12345678901\",\n \"nif\": \"987654321\",\n \"amount\": 29784.64,\n \"iban\": \"PT50000201231234567890154\",\n \"swift\": \"BESCPTPL\",\n \"entity\": \"Mock Entity\",\n \"paymentReference\": \"REF2024MOCK\"\n }\n ]\n },\n \"files\": [\n \"\"\n ]\n}"
},
"Login problem reaching authentication": {
"value": "{\n \"message\": \"Failed to login - Problem reaching the authentication page.\"\n}"
},
"Loading page timeout": {
"value": "{\n \"message\": \"Problem loading the page (timeout)\"\n}"
},
"Failed to extract data": {
"value": "{\n \"message\": \"Failed to extract data\"\n}"
},
"Invalid credentials": {
"value": "{\n \"message\": \"Failed to login - Invalid Credentials\"\n}"
},
"Login timeout": {
"value": "{\n \"message\": \"Failed to login - Website Timeout\"\n}"
},
"No access": {
"value": "{\n\t\"message\":\"No permissions to access this operation.\"\n}"
},
"No data found": {
"value": "{\n\t\"message\":\"No data found\"\n}"
},
"Recovery required": {
"value": "{\n\t\"message\":\"Requires password recovery\"\n}"
},
"Error in authentication": {
"value": "{\n\t\"message\":\"Failed to login - Error in authentication process\"\n}"
}
},
"schema": {
"oneOf": [
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "A human-readable message providing additional information about the response, such as error details or informative status updates"
},
"data": {
"type": "object",
"properties": {
"requestId": {
"type": "string",
"description": "Unique identifier for the request"
},
"paymentDocs": {
"type": "array",
"description": "List of TSU payment documents",
"items": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"description": "Unique identifier for the document"
},
"emissionDate": {
"type": "string",
"description": "Document emission date"
},
"validityDate": {
"type": "string",
"description": "Document validity date"
},
"emittedBy": {
"type": "string",
"description": "Name of the entity that emitted the document"
},
"niss": {
"type": "string",
"description": "Emitting entity NISS"
},
"nif": {
"type": "string",
"description": "Emitting entity NIF"
},
"amount": {
"type": "number",
"description": "Amount to Pay"
},
"iban": {
"type": "string",
"description": "IBAN receiving entity"
},
"swift": {
"type": "string",
"description": "SWIFT receiving entity"
},
"entity": {
"type": "string",
"description": "Receiving entity"
},
"paymentReference": {
"type": "string",
"description": "Payment reference associated with the payment document"
}
}
}
}
}
},
"files": {
"type": "array",
"description": "A list of files, each encoded as a Base64 string. Used when multiple files are included in the response.",
"items": {
"type": "string"
}
}
}
},
{
"title": "Login problem reaching authentication",
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Failed to login - Problem reaching the authentication page."
}
}
},
{
"title": "Loading page timeout",
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Problem loading the page (timeout)"
}
}
},
{
"title": "Failed to extract data",
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Failed to extract data"
}
}
},
{
"title": "Invalid credentials",
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Failed to login - Invalid Credentials"
}
}
},
{
"title": "Login timeout",
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Failed to login - Website Timeout"
}
}
},
{
"title": "No access",
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "No permissions to access this operation."
}
}
},
{
"title": "No data found",
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "No data found."
}
}
},
{
"title": "Recovery required",
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Requires password recovery"
}
}
},
{
"title": "Error in authentication",
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Failed to login - Error in authentication process"
}
}
}
]
}
}
}
},
"401": {
"description": "401",
"content": {
"text/plain": {
"examples": {
"Result": {
"value": "\n\n\n\n\tHTTP Status 401 – Unauthorized\n\t\n\n\n\n\tHTTP Status 401 – Unauthorized
\n\n\n"
}
}
}
}
},
"503": {
"description": "503",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"message\": \"Service ss-payref-tsu is currently unavailable\"\n}"
}
},
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Service ss-payref-tsu is currently unavailable"
}
}
}
}
}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```