post
https://api.somossimpay.com.br/v3/billpix
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
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Endpoint
POST /v3/billpix
Send all dates in UTC-0, with milliseconds.due_date,expiration_dateandfine_datemust use ISO 8601 with theZsuffix: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:00are rejected.
Headers
| Parameter | Type | Description | Example |
|---|---|---|---|
| Authorization | String | Bearer + Access_token | Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo |
| hmac | String | HMAC (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"
}| Field | Type | Description | Required or Optional |
|---|---|---|---|
| amount | Decimal | Amount to be charged, in BRL. Must be greater than 0, with up to 2 decimal places. | required |
| due_date | DateTime | Due date. Format YYYY-MM-DDTHH:MM:SS.sssZ (UTC-0). Must be a future date. | required |
| expiration_date | DateTime | After 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_date | DateTime | When the late-payment fine starts. Format YYYY-MM-DDTHH:MM:SS.sssZ. At least 1 day after due_date. | required |
| type_fine | String | Fine type: VALUE (fixed amount in BRL) or PERCENT (percentage of amount). NONE is not accepted. | required |
| fine | Decimal | Fine amount (VALUE) or percentage (PERCENT). Must be greater than 0. | required |
| type_fees | String | Interest type: NONE, VALUE or PERCENT. Default: NONE. | optional |
| fees | Decimal | Interest amount or percentage. Required and greater than 0 when type_fees is VALUE or PERCENT. | optional |
| type_discount | String | Discount type: NONE, VALUE or PERCENT. Default: NONE. | optional |
| discount | Decimal | Discount amount or percentage. Required and greater than 0 when type_discount is VALUE or PERCENT. | optional |
| type_abatement | String | Rebate type: NONE, VALUE or PERCENT. Default: NONE. | optional |
| abatement | Decimal | Rebate amount or percentage. Required and greater than 0 when type_abatement is VALUE or PERCENT. | optional |
| type_document | String | Type of the payer's document: CPF or CNPJ. | required |
| debtor_document | String | Payer's CPF (11 digits) or CNPJ (14 digits). Can include formatting. Check digits are validated. | required |
| debtor_name | String | Payer's full name or company name. Cannot be blank. | required |
| message | String | Message to the payer, printed on the PDF and shown when paying. Up to 200 characters. | optional |
| source_account_branch_identifier | String | Branch/agency number of the account that will receive the payment. | required |
| source_account_number | String | Account number that will receive the payment. | required |
| tag | String | Your 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"
}| Field | Type | Description |
|---|---|---|
| worked | Boolean | Always true for successful requests. |
| billpix_id | Integer | Pix Bill ID. Use it to query the charge and get a new PDF link. |
| 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). The payer can paste it in any banking app. |
| base_64_image | String | QR Code image (PNG) in base64, ready to embed. 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 | Charge status. Always NEW right after creation. See the status table in Pix Bill API. |
| account_number | String | Account number that will receive the payment. |
| agency_number | String | Branch/agency number of the account that will receive the payment. |
| tx_id | String | Pix transaction identifier (txid) of the charge. Used to reconcile the payment. |
| tag | String | Tag sent in the request. null when not sent. |
| pdf_url | String | Temporary link to download the PDF document. null when the PDF could not be generated; the charge is still valid and payable. |
Error Responses
| HTTP Code | Error Message | Description |
|---|---|---|
| 400 | HMAC header required for API audience | The hmac header was not sent. |
| 400 | HMAC invalid | The hmac header does not match the request body. Sign exactly the body you send. See HMAC Documentation. |
| 400 | field_name: Field required | A required field is missing. The message starts with the name of the field. |
| 400 | due_date: Invalid format | A date is not in the YYYY-MM-DDTHH:MM:SS.sssZ format. The same message is returned for expiration_date and fine_date. |
| 400 | due_date: Is less than current date | A date is in the past. The same message is returned for expiration_date and fine_date. |
| 400 | type_fine: Billpix requires a fine type | type_fine was sent as NONE. A Pix Bill always has a fine: use VALUE or PERCENT. |
| 400 | Expiration date must be greater than due date | expiration_date is equal to or before due_date. |
| 400 | Fine date must be greater than due date | fine_date is equal to or before due_date. |
| 400 | Difference between expiration date and due date must be at least one day | expiration_date must be at least 1 day after due_date. |
| 400 | Difference between fine date and due date must be at least one day | fine_date must be at least 1 day after due_date. |
| 400 | Debtor Document is invalid | debtor_document is not a valid CPF or CNPJ, or does not match type_document. |
| 400 | Missing debtor_name field | debtor_name is blank. |
| 400 | Fees must be greater than zero | type_fees is VALUE or PERCENT but fees is missing or 0. The same applies to Discount and Abatement. |
| 400 | Missing type_fees field | fees was sent while type_fees is NONE. The same applies to type_discount and type_abatement. |
| 400 | Requested amount exceeds the allowed limit | amount is above the maximum allowed for QR Code generation on the account. The message shows the maximum amount allowed. |
| 400 | Pix Key not found | The receiving account has no PIX key registered. Register a key with the DICT API before issuing a Pix Bill. |
| 400 | Cannot create Billpix for closing account | The receiving account is being closed and cannot issue new charges. |
| 401 | Unauthorized | Invalid or missing authentication token. Ensure you are sending a valid Bearer token. |
| 404 | Account not found | The 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:
amountmust 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_dateandfine_datemust each be at least 1 day afterdue_datetype_finemust beVALUEorPERCENT, andfinemust be greater than 0- Interest, discount and rebate are optional. When their type is
VALUEorPERCENT, the matching value must be greater than 0 debtor_documentmust be a valid CPF or CNPJ (check digits are validated) matchingtype_documentmessageaccepts up to 200 characters- The receiving account must have at least one PIX key registered
Important Notes:
- The
hmacheader signs the exact JSON body you send. Changing any field after signing makes the request fail withHMAC invalid pdf_urlis 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_urlcomes back asnull; deliverpix_copy_and_pasteto the payer instead - A
QR_CODE_COPY_AND_PASTE_CREATEDwebhook is sent when the Pix Bill is issued, andQR_CODE_COPY_AND_PASTE_PAIDwhen it is paid. See Webhook Events
400Bad request - Invalid parameters or HMAC
401Unauthorized - Invalid or missing authentication
404Account not found
