---
updatedAt: 2026-02-12T18:28:25.000Z
agentTools:
  projectIndex: https://developers.bizapis.com/llms.txt
---

# AT-PAYREF-IRS (Autoridade Tributária Referencia de Pagamento IRS)

Retrieve payment references for IRS

<br />

<Callout icon="🚧" theme="warn">
  # 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)
</Callout>

# 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"
        },
        "currentPaymentDocs" : {
          "type" : "array",
          "description" : "List of current payment documents",
          "items" : {
            "type" : "object",
            "properties" : {
              "service" : {
                "type" : "string",
                "description" : "Unique identifier for the service request"
              },
              "documentId" : {
                "type" : "string",
                "description" : "Unique identifier for the document"
              },
              "paymentReference" : {
                "type" : "string",
                "description" : "Payment reference associated with the payment document"
              },
              "amount" : {
                "type" : "number",
                "description" : "Amount to pay"
              },
              "paymentDueDate" : {
                "type" : "string",
                "description" : "Due date for the payment"
              }
            }
          }
        },
        "missingPaymentDocs" : {
          "type" : "array",
          "description" : "List of missing payment documents",
          "items" : {
            "type" : "object",
            "properties" : {
              "service" : {
                "type" : "string",
                "description" : "Unique identifier for the service request"
              },
              "documentId" : {
                "type" : "string",
                "description" : "Unique identifier for the document"
              },
              "paymentReference" : {
                "type" : "string",
                "description" : "Payment reference associated with the payment document"
              },
              "amount" : {
                "type" : "number",
                "description" : "Amount to pay"
              },
              "paymentDueDate" : {
                "type" : "string",
                "description" : "Due date for the payment"
              }
            }
          }
        }
      }
    },
    "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"
        },
        "currentPaymentDocs" : {
          "type" : "array",
          "description" : "Lista de documentos de pagamento atuais",
          "items" : {
            "type" : "object",
            "properties" : {
              "service" : {
                "type" : "string",
                "description" : "Identificador único do pedido de serviço"
              },
              "documentId" : {
                "type" : "string",
                "description" : "Identificador único do documento"
              },
              "paymentReference" : {
                "type" : "string",
                "description" : "Referência de pagamento associada ao documento de pagamento"
              },
              "amount" : {
                "type" : "number",
                "description" : "Montante a pagar"
              },
              "paymentDueDate" : {
                "type" : "string",
                "description" : "Data limite para pagamento"
              }
            }
          }
        },
        "missingPaymentDocs" : {
          "type" : "array",
          "description" : "Lista de documentos de pagamento em falta",
          "items" : {
            "type" : "object",
            "properties" : {
              "service" : {
                "type" : "string",
                "description" : "Identificador único do pedido de serviço"
              },
              "documentId" : {
                "type" : "string",
                "description" : "Identificador único do documento"
              },
              "paymentReference" : {
                "type" : "string",
                "description" : "Referência de pagamento associada ao documento de pagamento"
              },
              "amount" : {
                "type" : "number",
                "description" : "Montante a pagar"
              },
              "paymentDueDate" : {
                "type" : "string",
                "description" : "Data limite para 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

📖 **<Anchor label="View complete error codes reference →" target="_blank" href="https://developers.bizapis.com/reference/status-codes#/">View complete error codes reference →</Anchor>**

# 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": {
    "/at-payref-irs": {
      "post": {
        "summary": "AT-PAYREF-IRS (Autoridade Tributária Referencia de Pagamento IRS)",
        "description": "Retrieve payment references for IRS",
        "operationId": "at-payref-irs-autoridade-tributária-referencia-de-pagamento-irs",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "user",
                  "password"
                ],
                "properties": {
                  "user": {
                    "type": "string",
                    "description": "Taxpayer number",
                    "default": "test"
                  },
                  "password": {
                    "type": "string",
                    "description": "\"Autoridade Tributaria\" access password",
                    "default": "test"
                  }
                }
              },
              "examples": {
                "request": {
                  "value": {
                    "user": "test",
                    "password": "test"
                  }
                },
                "Loading problem reaching authentication": {
                  "value": {
                    "user": "<user>",
                    "password": "reachAuthentication"
                  }
                },
                "Loading page timeout": {
                  "value": {
                    "user": "<user>",
                    "password": "pageTimeout"
                  }
                },
                "Failed extract data": {
                  "value": {
                    "user": "<user>",
                    "password": "extractData"
                  }
                },
                "Invalid credentials": {
                  "value": {
                    "user": "<user>",
                    "password": "invalidCredentials"
                  }
                },
                "Login Timeout": {
                  "value": {
                    "user": "<user>",
                    "password": "loginTimeout"
                  }
                },
                "No access": {
                  "value": {
                    "user": "<user>",
                    "password": "nopermission"
                  }
                },
                "No data found": {
                  "value": {
                    "user": "<user>",
                    "password": "nodatafound"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"data\": {\n        \"currentPaymentDocs\": [\n            {\n                \"service\": \"IRS\",\n                \"documentId\": \"DOC123456\",\n                \"paymentReference\": \"123 456 789 012\",\n                \"amount\": 148.22,\n                \"paymentDueDate\": \"2025-08-31\"\n            }\n        ],\n        \"missingPaymentDocs\": [\n            {\n                \"service\": \"IRS\",\n                \"documentId\": \"DOC345678\",\n                \"paymentReference\": \"123 456 789 012\",\n                \"amount\": 148.22,\n                \"paymentDueDate\": \"2022-08-31\"\n            }\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}"
                  }
                },
                "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"
                            },
                            "currentPaymentDocs": {
                              "type": "array",
                              "description": "List of current payment documents",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "service": {
                                    "type": "string",
                                    "description": "Unique identifier for the service request"
                                  },
                                  "documentId": {
                                    "type": "string",
                                    "description": "Unique identifier for the document"
                                  },
                                  "paymentReference": {
                                    "type": "string",
                                    "description": "Payment reference associated with the payment document"
                                  },
                                  "amount": {
                                    "type": "number",
                                    "description": "Amount to pay"
                                  },
                                  "paymentDueDate": {
                                    "type": "string",
                                    "description": "Due date for the payment"
                                  }
                                }
                              }
                            },
                            "missingPaymentDocs": {
                              "type": "array",
                              "description": "List of missing payment documents",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "service": {
                                    "type": "string",
                                    "description": "Unique identifier for the service request"
                                  },
                                  "documentId": {
                                    "type": "string",
                                    "description": "Unique identifier for the document"
                                  },
                                  "paymentReference": {
                                    "type": "string",
                                    "description": "Payment reference associated with the payment document"
                                  },
                                  "amount": {
                                    "type": "number",
                                    "description": "Amount to pay"
                                  },
                                  "paymentDueDate": {
                                    "type": "string",
                                    "description": "Due date for the payment"
                                  }
                                }
                              }
                            }
                          }
                        },
                        "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."
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "401",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": "<!doctype html>\n<html lang=\"en\">\n\n<head>\n\t<title>HTTP Status 401 – Unauthorized</title>\n\t<style type=\"text/css\">\n\t\tbody {\n\t\t\tfont-family: Tahoma, Arial, sans-serif;\n\t\t}\n\n\t\th1,\n\t\th2,\n\t\th3,\n\t\tb {\n\t\t\tcolor: white;\n\t\t\tbackground-color: #525D76;\n\t\t}\n\n\t\th1 {\n\t\t\tfont-size: 22px;\n\t\t}\n\n\t\th2 {\n\t\t\tfont-size: 16px;\n\t\t}\n\n\t\th3 {\n\t\t\tfont-size: 14px;\n\t\t}\n\n\t\tp {\n\t\t\tfont-size: 12px;\n\t\t}\n\n\t\ta {\n\t\t\tcolor: black;\n\t\t}\n\n\t\t.line {\n\t\t\theight: 1px;\n\t\t\tbackground-color: #525D76;\n\t\t\tborder: none;\n\t\t}\n\t</style>\n</head>\n\n<body>\n\t<h1>HTTP Status 401 – Unauthorized</h1>\n</body>\n\n</html>"
                  }
                }
              }
            }
          },
          "503": {
            "description": "503",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"message\": \"Service at-payref-irs is currently unavailable\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Service at-payref-irs is currently unavailable"
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```