Pix Bill API

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 Authorization header
  • HMAC Signature: Include in the hmac header 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

StatusDescriptionNext Steps
NEWPix Bill issued and waiting for the payerDeliver the PDF or the copy and paste code and wait for the payment webhook
PROCESSINGPayment is being settledWait for the final status
PAIDPayment received and credited to your accountNo action needed
EXPIREDexpiration_date passed without paymentIssue a new Pix Bill if you still want to charge
CANCELEDThe charge was cancelled before paymentNo action needed
CHARGEBACKThe payment was refunded to the payerCheck 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).

FieldWhat it means
due_dateLast day to pay without a fine
fine_dateWhen the late-payment fine starts. At least 1 day after due_date
expiration_dateAfter 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 fieldValue fieldRequiredAccepted types
type_finefinerequiredVALUE (fixed amount in BRL) or PERCENT (percentage of amount)
type_feesfeesoptionalNONE (default), VALUE or PERCENT
type_discountdiscountoptionalNONE (default), VALUE or PERCENT
type_abatementabatementoptionalNONE (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_url is 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_url comes back as null and you can deliver the pix_copy_and_paste code instead.

Best Practices

  1. Store both IDs: Keep billpix_id to fetch the PDF again and qr_code_id to use the Cashin API queries and chargebacks
  2. Download the PDF right away: The link expires; store the file if you need to send it again later
  3. Use webhooks: Register the QR_CODE_COPY_AND_PASTE_PAID event to know when the Pix Bill was paid. See Webhook Events
  4. Use tags: Send a tag (e.g., your invoice number) to find the charge later with the Cashin API tag query
  5. Keep the message short and clear: It is printed on the document and shown to the payer (up to 200 characters)