Create a Pix Bill

Issues a Pix charge with due date and returns the QR Code, the copy and paste code and a link to the boleto-style PDF document.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Endpoint

POST /v3/billpix
⏰

Send all dates in UTC-0, with milliseconds. due_date, expiration_date and fine_date must use ISO 8601 with the Z suffix: YYYY-MM-DDTHH:MM:SS.sssZ (e.g., 2026-11-30T23:59:59.000Z). Dates without milliseconds or with a timezone offset such as -03:00 are rejected.

Headers

ParameterTypeDescriptionExample
AuthorizationStringBearer + Access_tokenBearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo
hmacStringHMAC (Hash-based Message Authentication Code) is an authentication algorithm that combines a private key with a message to create a Message Authentication Code (MAC).hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6

Body Details

{
  "amount": 250.00,
  "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.00,
  "type_fees": "PERCENT",
  "fees": 1.00,
  "type_discount": "VALUE",
  "discount": 10.00,
  "type_abatement": "NONE",
  "type_document": "CPF",
  "debtor_document": "529.982.247-25",
  "debtor_name": "Maria Santos",
  "message": "November monthly fee",
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "tag": "INV-2026-1130"
}
FieldTypeDescriptionRequired or Optional
amountDecimalAmount to be charged, in BRL. Must be greater than 0, with up to 2 decimal places.required
due_dateDateTimeDue date. Format YYYY-MM-DDTHH:MM:SS.sssZ (UTC-0). Must be a future date.required
expiration_dateDateTimeAfter this date the Pix Bill can no longer be paid. Format YYYY-MM-DDTHH:MM:SS.sssZ. At least 1 day after due_date.required
fine_dateDateTimeWhen the late-payment fine starts. Format YYYY-MM-DDTHH:MM:SS.sssZ. At least 1 day after due_date.required
type_fineStringFine type: VALUE (fixed amount in BRL) or PERCENT (percentage of amount). NONE is not accepted.required
fineDecimalFine amount (VALUE) or percentage (PERCENT). Must be greater than 0.required
type_feesStringInterest type: NONE, VALUE or PERCENT. Default: NONE.optional
feesDecimalInterest amount or percentage. Required and greater than 0 when type_fees is VALUE or PERCENT.optional
type_discountStringDiscount type: NONE, VALUE or PERCENT. Default: NONE.optional
discountDecimalDiscount amount or percentage. Required and greater than 0 when type_discount is VALUE or PERCENT.optional
type_abatementStringRebate type: NONE, VALUE or PERCENT. Default: NONE.optional
abatementDecimalRebate amount or percentage. Required and greater than 0 when type_abatement is VALUE or PERCENT.optional
type_documentStringType of the payer's document: CPF or CNPJ.required
debtor_documentStringPayer's CPF (11 digits) or CNPJ (14 digits). Can include formatting. Check digits are validated.required
debtor_nameStringPayer's full name or company name. Cannot be blank.required
messageStringMessage to the payer, printed on the PDF and shown when paying. Up to 200 characters.optional
source_account_branch_identifierStringBranch/agency number of the account that will receive the payment.required
source_account_numberStringAccount number that will receive the payment.required
tagStringYour own reference for the charge (e.g., invoice or order number). Can be used to query the charge later.optional

Request Examples

Pix Bill with fine only:

POST /v3/billpix
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json

{
  "amount": 150.00,
  "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": "VALUE",
  "fine": 5.00,
  "type_document": "CNPJ",
  "debtor_document": "11222333000181",
  "debtor_name": "Empresa XYZ Ltda",
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456"
}

Pix Bill with interest, discount and message:

POST /v3/billpix
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json

{
  "amount": 250.00,
  "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.00,
  "type_fees": "PERCENT",
  "fees": 1.00,
  "type_discount": "VALUE",
  "discount": 10.00,
  "type_document": "CPF",
  "debtor_document": "529.982.247-25",
  "debtor_name": "Maria Santos",
  "message": "November monthly fee",
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "tag": "INV-2026-1130"
}

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": "NEW",
  "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. Use it to query the charge and get a new PDF link.
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). The payer can paste it in any banking app.
base_64_imageStringQR Code image (PNG) in base64, ready to embed. 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.
statusStringCharge status. Always NEW right after creation. See the status table in Pix Bill API.
account_numberStringAccount number that will receive the payment.
agency_numberStringBranch/agency number of the account that will receive the payment.
tx_idStringPix transaction identifier (txid) of the charge. Used to reconcile the payment.
tagStringTag sent in the request. null when not sent.
pdf_urlStringTemporary link to download the PDF document. null when the PDF could not be generated; the charge is still valid and payable.

Error Responses

HTTP CodeError MessageDescription
400HMAC header required for API audienceThe hmac header was not sent.
400HMAC invalidThe hmac header does not match the request body. Sign exactly the body you send. See HMAC Documentation.
400field_name: Field requiredA required field is missing. The message starts with the name of the field.
400due_date: Invalid formatA date is not in the YYYY-MM-DDTHH:MM:SS.sssZ format. The same message is returned for expiration_date and fine_date.
400due_date: Is less than current dateA date is in the past. The same message is returned for expiration_date and fine_date.
400type_fine: Billpix requires a fine typetype_fine was sent as NONE. A Pix Bill always has a fine: use VALUE or PERCENT.
400Expiration date must be greater than due dateexpiration_date is equal to or before due_date.
400Fine date must be greater than due datefine_date is equal to or before due_date.
400Difference between expiration date and due date must be at least one dayexpiration_date must be at least 1 day after due_date.
400Difference between fine date and due date must be at least one dayfine_date must be at least 1 day after due_date.
400Debtor Document is invaliddebtor_document is not a valid CPF or CNPJ, or does not match type_document.
400Missing debtor_name fielddebtor_name is blank.
400Fees must be greater than zerotype_fees is VALUE or PERCENT but fees is missing or 0. The same applies to Discount and Abatement.
400Missing type_fees fieldfees was sent while type_fees is NONE. The same applies to type_discount and type_abatement.
400Requested amount exceeds the allowed limitamount is above the maximum allowed for QR Code generation on the account. The message shows the maximum amount allowed.
400Pix Key not foundThe receiving account has no PIX key registered. Register a key with the DICT API before issuing a Pix Bill.
400Cannot create Billpix for closing accountThe receiving account is being closed and cannot issue new charges.
401UnauthorizedInvalid or missing authentication token. Ensure you are sending a valid Bearer token.
404Account not foundThe branch and account number do not match an account you can access.

All errors are returned in the standard error envelope:

{
  "worked": false,
  "detail": "Expiration date must be greater than due date",
  "message": "Expiration date must be greater than due date",
  "data": null
}

Business Rules

Validations:

  • amount must be greater than 0 and cannot exceed the maximum amount allowed for QR Code generation on the account
  • All dates are required, must be in the future and must use YYYY-MM-DDTHH:MM:SS.sssZ (UTC-0, with milliseconds)
  • expiration_date and fine_date must each be at least 1 day after due_date
  • type_fine must be VALUE or PERCENT, and fine must be greater than 0
  • Interest, discount and rebate are optional. When their type is VALUE or PERCENT, the matching value must be greater than 0
  • debtor_document must be a valid CPF or CNPJ (check digits are validated) matching type_document
  • message accepts up to 200 characters
  • The receiving account must have at least one PIX key registered

Important Notes:

  • The hmac header signs the exact JSON body you send. Changing any field after signing makes the request fail with HMAC invalid
  • pdf_url is a temporary link. Download and store the file, or call Get a Pix Bill to get a new link to the same document
  • The PDF is generated at issuance and is not rebuilt later. Changes to your logo or colors do not affect Pix Bill already issued
  • The PDF shows the amount and discount at issuance. The fine and interest are calculated when the payer pays after the due date
  • If the PDF cannot be generated, the charge is still created and payable. pdf_url comes back as null; deliver pix_copy_and_paste to the payer instead
  • A QR_CODE_COPY_AND_PASTE_CREATED webhook is sent when the Pix Bill is issued, and QR_CODE_COPY_AND_PASTE_PAID when it is paid. See Webhook Events
Body Params
number
required

Amount to be charged, in BRL. Greater than 0, up to 2 decimal places.

string
required

Due date, UTC-0: YYYY-MM-DDTHH:MM:SS.sssZ. Must be a future date.

string
required

Last date the charge can be paid, UTC-0: YYYY-MM-DDTHH:MM:SS.sssZ. At least 1 day after due_date.

string
required

When the late-payment fine starts, UTC-0: YYYY-MM-DDTHH:MM:SS.sssZ. At least 1 day after due_date.

string
enum
required

Fine type: VALUE or PERCENT.

Allowed:
number
required

Fine amount (VALUE) or percentage (PERCENT). Greater than 0.

string
enum

Interest type. Default NONE.

Allowed:
number

Interest amount or percentage. Required when type_fees is VALUE or PERCENT.

string
enum

Discount type. Default NONE.

Allowed:
number

Discount amount or percentage. Required when type_discount is VALUE or PERCENT.

string
enum

Rebate type. Default NONE.

Allowed:
number

Rebate amount or percentage. Required when type_abatement is VALUE or PERCENT.

string
enum
required

Type of the payer's document.

Allowed:
string
required

Payer's CPF or CNPJ. Can include formatting.

string
required

Payer's full name or company name.

string
length ≤ 200

Message to the payer, printed on the PDF. Up to 200 characters.

string
required

Branch/agency number of the receiving account.

string
required

Account number of the receiving account.

string

Your own reference for the charge.

Headers
string
required

Bearer + Access_token

string
required

HMAC signature of the raw JSON body. See HMAC Documentation.

Responses

400

Bad request - Invalid parameters or HMAC

401

Unauthorized - Invalid or missing authentication

404

Account not found

Language
LoadingLoading…
Response
Choose an example:
application/json