get
https://api.somossimpay.com.br/v3/billpix/
Retrieves a Pix Bill by its ID, with its current status and a new temporary link to the PDF document.
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Endpoint
GET /v3/billpix/{billpix_id}
Headers
| Parameter | Type | Description | Example |
|---|---|---|---|
| Authorization | String | Bearer + Access_token | Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo |
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| billpix_id | Integer | Pix Bill ID, returned as billpix_id when the charge was created. | 55 |
Request Examples
Retrieve a Pix Bill:
GET /v3/billpix/55
Authorization: Bearer <access_token>Response Details
{
"worked": true,
"billpix_id": 55,
"qr_code_id": 98766,
"uuid": "9d36b84f-c70b-478e-a811-64e2b1cb4d13",
"pix_copy_and_paste": "00020101021226990014br.gov.bcb.pix2577qrcode.example.com/cobv/9d36b84fc70b478ea81164e2b1cb4d135204000053039865802BR5925Example Company Name6014CIDADE EXEMPLO62070503***6304ABCD",
"base_64_image": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAIAAAD2HxkiAAAA...",
"base_64_image_url": "https://qrcode.example.com/9d36b84f-c70b-478e-a811-64e2b1cb4d13.png",
"amount": 250.0,
"due_date": "2026-11-30T23:59:59.000Z",
"expiration_date": "2026-12-15T23:59:59.000Z",
"fine_date": "2026-12-01T00:00:00.000Z",
"type_fine": "PERCENT",
"fine": 2.0,
"type_fees": "PERCENT",
"fees": 1.0,
"type_discount": "VALUE",
"discount": 10.0,
"type_abatement": "NONE",
"abatement": null,
"debtor_name": "Maria Santos",
"debtor_document": "52998224725",
"type_document": "CPF",
"message": "November monthly fee",
"status": "PAID",
"account_number": "123456",
"agency_number": "0001",
"tx_id": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
"tag": "INV-2026-1130",
"pdf_url": "https://documents.example.com/billpix/9d36b84f-c70b-478e-a811-64e2b1cb4d13.pdf?signature=example"
}| Field | Type | Description |
|---|---|---|
| worked | Boolean | Always true for successful requests. |
| billpix_id | Integer | Pix Bill ID. |
| qr_code_id | Integer | ID of the PIX QR Code behind the Pix Bill. Use it with the Cashin API status queries and chargebacks. |
| uuid | String | Unique identifier of the QR Code. |
| pix_copy_and_paste | String | PIX copy and paste code (EMV format). |
| base_64_image | String | QR Code image (PNG) in base64. null when not available. |
| base_64_image_url | String | URL to download the QR Code image (PNG). |
| amount | Float | Amount charged. |
| due_date | DateTime | Due date (UTC-0). |
| expiration_date | DateTime | Expiration date (UTC-0). |
| fine_date | DateTime | Date when the fine starts (UTC-0). |
| type_fine | String | Fine type: VALUE or PERCENT. |
| fine | Float | Fine amount or percentage. |
| type_fees | String | Interest type: NONE, VALUE or PERCENT. |
| fees | Float | Interest amount or percentage. null when type_fees is NONE. |
| type_discount | String | Discount type: NONE, VALUE or PERCENT. |
| discount | Float | Discount amount or percentage. null when type_discount is NONE. |
| type_abatement | String | Rebate type: NONE, VALUE or PERCENT. |
| abatement | Float | Rebate amount or percentage. null when type_abatement is NONE. |
| debtor_name | String | Payer's name. |
| debtor_document | String | Payer's CPF or CNPJ, digits only. |
| type_document | String | Type of the payer's document: CPF or CNPJ. |
| message | String | Message to the payer. null when not sent. |
| status | String | Current status: NEW, PROCESSING, PAID, EXPIRED, CANCELED or CHARGEBACK. See Pix Bill API. |
| account_number | String | Account number that receives the payment. |
| agency_number | String | Branch/agency number of the account that receives the payment. |
| tx_id | String | Pix transaction identifier (txid) of the charge. |
| tag | String | Tag sent when the charge was created. null when not sent. |
| pdf_url | String | New temporary link to the PDF document issued with the charge. null when no PDF is available for this Pix Bill. |
Error Responses
| HTTP Code | Error Message | Description |
|---|---|---|
| 400 | billpix_id: Input should be a valid integer, unable to parse string as an integer | billpix_id in the path is not a number. |
| 401 | Unauthorized | Invalid or missing authentication token. Ensure you are sending a valid Bearer token. |
| 404 | Billpix not found | No Pix Bill was found with this ID, or it belongs to an account you cannot access. |
All errors are returned in the standard error envelope:
{
"worked": false,
"detail": "Billpix not found",
"message": "Billpix not found",
"data": null
}Business Rules
Validations:
billpix_idmust be the ID returned when the Pix Bill was created- Only Pix Bill issued from accounts you can access are returned
Important Notes:
- Each call returns a new temporary
pdf_url. The link points to the same document generated at issuance; the PDF is not rebuilt statusreflects the current state of the charge, so this endpoint can also be used to check whether the Pix Bill was paid. Prefer theQR_CODE_COPY_AND_PASTE_PAIDwebhook instead of polling. See Webhook Events
401Unauthorized - Invalid or missing authentication
404Billpix not found
