Issue Pix charges with due date delivered as a boleto-style PDF, with your logo and colors, ready to send to the payer.
The Pix Bill API issues a Pix charge with due date and delivers it as a PDF document in the boleto layout. The payer receives a familiar document (receiver, due date, amount, discount) but pays it with Pix, by scanning the QR Code or pasting the copy and paste code printed on it.
Each Pix Bill is a regular dynamic PIX QR Code with due date. Everything you already use for QR Codes in the Cashin API keeps working for it: payment webhooks, status queries and chargebacks.
Key Features
- Charge with due date: Due date, expiration date and late-payment fine are part of every Pix Bill
- Interest, discount and rebate: Optionally add interest, a discount or a rebate, as a fixed value or a percentage
- Ready-to-send PDF: A boleto-style document with your logo and brand color, the QR Code and the copy and paste code
- Message to the payer: A short message printed on the document and shown to the payer
- Fresh download link on demand: Query the Pix Bill at any time to get a new link to the same PDF
Available Endpoints
- Create a Pix Bill - Issue the charge and receive the QR Code, the copy and paste code and the PDF link
- Get a Pix Bill - Retrieve the charge details, its status and a new PDF link
Authentication
All Pix Bill API endpoints require:
- Bearer Token: Include in the
Authorizationheader - HMAC Signature: Include in the
hmacheader when creating a Pix Bill. See HMAC Documentation
Pix Bill Flow
┌──────────────────────────────────────────────┐
│ POST /v3/billpix │ ← You issue the Pix Bill
└───────────────────────┬──────────────────────┘
│ response: billpix_id, qr_code_id,
│ pix_copy_and_paste and pdf_url
│ webhook: QR_CODE_COPY_AND_PASTE_CREATED
↓
┌──────────────────────┐
│ Send the PDF or the │ ← Download it from pdf_url and deliver
│ copy and paste code │ it to the payer (email, app, chat)
└──────────┬───────────┘
↓
┌─────────────┐
│ NEW │ ← Waiting for the payer
└──────┬──────┘
│
├─── Payer pays ──────→ ┌─────────────┐
│ │ PAID │ ← Money credited to your account
│ └─────────────┘
│ webhook: QR_CODE_COPY_AND_PASTE_PAID
│
└─── Not paid until ──→ ┌─────────────┐
expiration_date │ EXPIRED │ ← Can no longer be paid
└─────────────┘
How to check where it is:
GET /v3/billpix/55 ← by Pix Bill ID
GET /v2/finance/status-pix-copy-and-paste?id=98766 ← by QR Code ID (Cashin API)
Both identifiers come back when you create the Pix Bill: billpix_id and qr_code_id.
Status Descriptions
| Status | Description | Next Steps |
|---|---|---|
| NEW | Pix Bill issued and waiting for the payer | Deliver the PDF or the copy and paste code and wait for the payment webhook |
| PROCESSING | Payment is being settled | Wait for the final status |
| PAID | Payment received and credited to your account | No action needed |
| EXPIRED | expiration_date passed without payment | Issue a new Pix Bill if you still want to charge |
| CANCELED | The charge was cancelled before payment | No action needed |
| CHARGEBACK | The payment was refunded to the payer | Check the chargeback in the Chargeback API |
Dates
Every Pix Bill has three dates. All of them are required and must be sent in UTC-0, in ISO 8601 with milliseconds and the Z suffix: YYYY-MM-DDTHH:MM:SS.sssZ (e.g., 2026-11-30T23:59:59.000Z).
| Field | What it means |
|---|---|
| due_date | Last day to pay without a fine |
| fine_date | When the late-payment fine starts. At least 1 day after due_date |
| expiration_date | After this date the Pix Bill can no longer be paid. At least 1 day after due_date |
Payment timeline example:
Due Date: November 30
Fine Date: December 1
Expiration: December 15
Payment until November 30: no fine
Payment from December 1 to 15: fine applied
Payment after December 15: expired, cannot be paid
Charge Modalities
The fine is required. Interest, discount and rebate are optional.
| Type field | Value field | Required | Accepted types |
|---|---|---|---|
| type_fine | fine | required | VALUE (fixed amount in BRL) or PERCENT (percentage of amount) |
| type_fees | fees | optional | NONE (default), VALUE or PERCENT |
| type_discount | discount | optional | NONE (default), VALUE or PERCENT |
| type_abatement | abatement | optional | NONE (default), VALUE or PERCENT |
When a type is VALUE or PERCENT, its value field must be greater than 0. When a type is NONE, leave the value field out.
The PDF Document
- The PDF shows your logo and brand color, the receiver name and document (masked), the bank, the issue date, the due date, the amount, the discount, the final amount, the QR Code, the copy and paste code and the
message. - The document is a snapshot taken at issuance. It is not rebuilt later: querying the Pix Bill returns a new link to the same file.
pdf_urlis a temporary link. Download the file and store it on your side, or call Get a Pix Bill whenever you need a new link.- If the PDF cannot be generated, the charge is still valid and can be paid:
pdf_urlcomes back asnulland you can deliver thepix_copy_and_pastecode instead.
Best Practices
- Store both IDs: Keep
billpix_idto fetch the PDF again andqr_code_idto use the Cashin API queries and chargebacks - Download the PDF right away: The link expires; store the file if you need to send it again later
- Use webhooks: Register the
QR_CODE_COPY_AND_PASTE_PAIDevent to know when the Pix Bill was paid. See Webhook Events - Use tags: Send a
tag(e.g., your invoice number) to find the charge later with the Cashin API tag query - Keep the message short and clear: It is printed on the document and shown to the payer (up to 200 characters)
