Get a Pix Bill

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
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Endpoint

GET /v3/billpix/{billpix_id}

Headers

ParameterTypeDescriptionExample
AuthorizationStringBearer + Access_tokenBearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo

Path Parameters

ParameterTypeDescriptionExample
billpix_idIntegerPix 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"
}
FieldTypeDescription
workedBooleanAlways true for successful requests.
billpix_idIntegerPix Bill ID.
qr_code_idIntegerID of the PIX QR Code behind the Pix Bill. Use it with the Cashin API status queries and chargebacks.
uuidStringUnique identifier of the QR Code.
pix_copy_and_pasteStringPIX copy and paste code (EMV format).
base_64_imageStringQR Code image (PNG) in base64. null when not available.
base_64_image_urlStringURL to download the QR Code image (PNG).
amountFloatAmount charged.
due_dateDateTimeDue date (UTC-0).
expiration_dateDateTimeExpiration date (UTC-0).
fine_dateDateTimeDate when the fine starts (UTC-0).
type_fineStringFine type: VALUE or PERCENT.
fineFloatFine amount or percentage.
type_feesStringInterest type: NONE, VALUE or PERCENT.
feesFloatInterest amount or percentage. null when type_fees is NONE.
type_discountStringDiscount type: NONE, VALUE or PERCENT.
discountFloatDiscount amount or percentage. null when type_discount is NONE.
type_abatementStringRebate type: NONE, VALUE or PERCENT.
abatementFloatRebate amount or percentage. null when type_abatement is NONE.
debtor_nameStringPayer's name.
debtor_documentStringPayer's CPF or CNPJ, digits only.
type_documentStringType of the payer's document: CPF or CNPJ.
messageStringMessage to the payer. null when not sent.
statusStringCurrent status: NEW, PROCESSING, PAID, EXPIRED, CANCELED or CHARGEBACK. See Pix Bill API.
account_numberStringAccount number that receives the payment.
agency_numberStringBranch/agency number of the account that receives the payment.
tx_idStringPix transaction identifier (txid) of the charge.
tagStringTag sent when the charge was created. null when not sent.
pdf_urlStringNew temporary link to the PDF document issued with the charge. null when no PDF is available for this Pix Bill.

Error Responses

HTTP CodeError MessageDescription
400billpix_id: Input should be a valid integer, unable to parse string as an integerbillpix_id in the path is not a number.
401UnauthorizedInvalid or missing authentication token. Ensure you are sending a valid Bearer token.
404Billpix not foundNo 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_id must 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
  • status reflects the current state of the charge, so this endpoint can also be used to check whether the Pix Bill was paid. Prefer the QR_CODE_COPY_AND_PASTE_PAID webhook instead of polling. See Webhook Events
Path Params
integer
required

Pix Bill ID.

Headers
string
required

Bearer + Access_token

Responses

401

Unauthorized - Invalid or missing authentication

404

Billpix not found

Language
LoadingLoading…
Response
Choose an example:
application/json