Skip to navigation

Due-date QR Code Guide

This guide explains how to issue PIX charges with a due date — the Pix “CobV” charge, with interest, penalty, discount and deduction.

Overview

The due-date QR Code is a single-use charge, like the Dynamic QR Code, but with boleto-style rules: it has a due day, an identified debtor and charges that change the amount according to the payment date. It fits:

  • Monthly fees and invoices - Charges with a set payment date
  • Boleto replacement - Same due date and charges, settled over Pix
  • Installment plans - One charge per installment, each with its own due date
Enabled per tenant

The due-date QR Code must be enabled for your tenant. Without it, creation returns 403 feature_disabled. Ask the CorpX team to enable it.

Integration Flow

┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Issue │ │ Debtor │ │ Webhook │
│ Charge │ ───► │ Pays QR │ ───► │ qrcode.paid │
└─────────────┘ └─────────────┘ └─────────────┘
│ │
▼ ▼
Returns EMV amount = amount paid
(with charges)

Step 1: Issue the charge

Request

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code/due-date" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: {tenant_id}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: invoice-2026-12" \
-d '{
"pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
"identifier": "invoice-2026-12",
"value": 150.00,
"dueDate": "2026-12-10",
"daysAfterDueDate": 5,
"discount": 10.00,
"interest": 1.50,
"penalty": 3.00,
"debtor": {
"name": "Maria Oliveira",
"document": "98765432100"
},
"message": "December fee"
}'

Body Parameters

FieldTypeRequiredDescription
pixKeystringYesPIX key of the receiving account (must be registered)
valuenumberYesOriginal charge amount in BRL, greater than zero, at most 2 decimal places
dueDatedateYesDue day, YYYY-MM-DD, Brasília time. Cannot be in the past
daysAfterDueDateintegerNoFor how many days after the due date the QR still accepts payment. Default 0
debtor.namestringYesDebtor name
debtor.documentstringYesDebtor CPF (11 digits) or CNPJ (14 digits); punctuation is ignored
deductionnumberNoDeduction in BRL
discountnumberNoDiscount in BRL for payment up to the due date
interestnumberNoInterest in BRL for payment after the due date
penaltynumberNoPenalty in BRL for payment after the due date
finalValuenumberNoAmount to pay up to the due date. When omitted, value − deduction − discount
receiverNamestringNoReceiver name shown to the payer. When omitted, the account holder
identifierstringRecommendedUnique charge identifier (up to 38 characters, charset [A-Za-z0-9._-]). When omitted, the API generates a UUID without hyphens
messagestringNoMessage shown to the payer (up to 140 characters)
Maximum term

The QR accepts payment until 23:59:59 (Brasília) on dueDate + daysAfterDueDate. That day cannot be more than 365 days from today. deduction + discount must be lower than value.

Success Response (201 Created)

{
"txid": "invoice-2026-12",
"emv": "00020101021226900014br.gov.bcb.pix2568qrcode.exemplo.com/cobv/invoice-2026-1252040000530398654061505802BR5914LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",
"type": "due-date",
"status": "ACTIVE",
"value": 150.00,
"message": "December fee",
"description": "December fee",
"identifier": "invoice-2026-12",
"accountId": "{accountId}",
"pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
"allowChange": false,
"expiresAt": "2026-12-16T02:59:59Z",
"dueDate": "2026-12-10",
"daysAfterDueDate": 5,
"deduction": 0,
"discount": 10.00,
"interest": 1.50,
"penalty": 3.00,
"finalValue": 140.00,
"debtor": {
"name": "Maria Oliveira",
"document": "98765432100"
},
"receiverName": "LOJA EXEMPLO"
}
FieldDescription
emvPIX Copy and Paste code. Render it as a QR
typeAlways due-date
expiresAtLast instant the QR accepts payment (end of dueDate + daysAfterDueDate, Brasília), in UTC
finalValueAmount to pay up to the due date
debtorDebtor given at issuance. Who actually paid comes in payer after payment

Step 2: Look up and cancel

Lookup and cancellation are the same as for the dynamic QR, by identifier:

curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code/lookup?identifier=invoice-2026-12" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: {tenant_id}"
curl -X DELETE "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code?identifier=invoice-2026-12" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: {tenant_id}"

The lookup returns type: "due-date" and the same due-date fields as the creation response (dueDate, daysAfterDueDate, charges, finalValue, debtor, receiverName). Statuses are those of the dynamic QR; EXPIRED means the last payment day passed without payment.

Step 3: Receive the webhook

Payment arrives as qrcode.paid, with data.type = "due-date". data.amount is the amount actually paid, which may differ from value: discount up to the due date, interest and penalty after it.

{
"id": "qrcode-paid-invoice-2026-12",
"type": "qrcode.paid",
"occurredAt": "2026-12-12T14:03:11.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-yourcompany",
"accountId": "{accountId}",
"data": {
"qrcodeId": "invoice-2026-12",
"identifier": "invoice-2026-12",
"accountId": "{accountId}",
"tenantId": "tenant-yourcompany",
"type": "due-date",
"amount": 154.50,
"endToEnd": "E0000000020261212140300000",
"transactionId": "171234-pix",
"status": "SUCCESS",
"receivedAt": "2026-12-12T14:03:11.000Z",
"payer": {
"name": "MARIA OLIVEIRA",
"document": "98765432100"
}
}
}

Reconcile by identifier and compare data.amount with the amount you expect for the payment date. Without payment by expiresAt, you receive qrcode.expired.

Permissions

The route uses the same scope as the dynamic QR, qrcode.manage (or api2/write). In the integrator dashboard, issuance requires the Issue due-date and Pix Location QR codes permission.

Common Errors

errorCodeHTTPCauseFix
missing_field400pixKey, dueDate, debtor.name, debtor.document or the receiver missingSend the required fields
invalid_document400debtor.document has neither 11 nor 14 digitsSend a valid CPF or CNPJ
invalid_field400Negative amount or more than 2 decimals, deduction + discount ≥ value, due date in the past or beyond 365 days, message over 140 charactersFix the terms
invalid_identifier400identifier outside the charset or over 38 charactersFix the identifier
invalid_payload400Malformed JSONFix the request body
feature_disabled403Product not enabled for the tenantAsk CorpX to enable it
policy_denied422A dynamic QR policy rule refused the issuanceSee violations — Policies and Rules

Next Steps