Overview

This is the single endpoint used to generate a dynamic PIX QR Code (also returned as a "copy and paste" string). There is only one endpoint — you control the type of QR Code that is generated simply by which fields you send in the request body.

There are two ways to use it:

• Simplified QR Code — Send only the essential fields (amount, source account, and expiration_date). This creates an immediate dynamic QR Code with no due date or fines. Ideal for quick payments, e-commerce checkouts, and POS scenarios.
• Full / Charge QR Code — Send the complete set of fields, including debtor information, due_date, expiration_date, and fine configuration. This creates a charge dynamic QR Code (similar to a boleto) with due dates and late-payment fines. Ideal for invoices, subscriptions, and formal billing.

📘

One endpoint, two modes

You do not need to call a different URL for each mode. The behavior is decided by the fields you include. If you send fine and date fields, you get a charge QR Code; if you omit them and use type_fine: "NONE", you get a simplified immediate QR Code.

Endpoint

POST /v2/finance/create-pix-copy-and-paste

Headers

Body Details

The table below lists every field accepted by the endpoint. The "Required" column shows when each field is needed depending on the type of QR Code you want to generate.

Mode 1 — Simplified QR Code (minimal fields)

Use this mode when you just need to receive a payment quickly and do not need billing rules. Set type_fine to NONE and omit the due date, fine, and fine date. Debtor information is optional.

Request Body

{
  "amount": 100.50,
  "type_fine": "NONE",
  "source_account_branch_identifier": "0001",
  "source_account_number": "12345678-9",
  "expiration_date": "2026-04-30T23:59:59",
  "tag": "Order #12345"
}

Request Example — minimal required fields

POST /v2/finance/create-pix-copy-and-paste
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b...
Content-Type: application/json

{
  "amount": 100.00,
  "type_fine": "NONE",
  "source_account_branch_identifier": "0001",
  "source_account_number": "12345678-9",
  "expiration_date": "2026-05-01T23:59:59"
}

Request Example — with optional debtor information

POST /v2/finance/create-pix-copy-and-paste
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b...
Content-Type: application/json

{
  "amount": 150.00,
  "type_fine": "NONE",
  "source_account_branch_identifier": "0001",
  "source_account_number": "12345678-9",
  "expiration_date": "2026-04-30T23:59:59",
  "debtor_document": "12345678900",
  "debtor_name": "João da Silva",
  "type_document": "CPF",
  "tag": "Order #12345"
}

Mode 2 — Full / Charge QR Code (all recommended fields)

Use this mode for invoices and formal billing. Send debtor information, a due_date, an expiration_date, and the fine configuration (type_fine, fine, fine_date). This generates a charge dynamic QR Code similar to a boleto.

Request Body

{
  "amount": 250.00,
  "type_fine": "VALUE",
  "fine": 10.00,
  "due_date": "2026-04-25T23:59:59",
  "expiration_date": "2026-05-10T23:59:59",
  "fine_date": "2026-04-26T23:59:59",
  "source_account_branch_identifier": "0001",
  "source_account_number": "12345678-9",
  "debtor_document": "12345678000190",
  "debtor_name": "Empresa XYZ Ltda",
  "type_document": "CNPJ",
  "tag": "Invoice #INV-2024-789"
}

Request Example — fixed fine (VALUE)

POST /v2/finance/create-pix-copy-and-paste
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b...
Content-Type: application/json

{
  "amount": 500.00,
  "type_fine": "VALUE",
  "fine": 25.00,
  "due_date": "2026-04-30T23:59:59",
  "expiration_date": "2026-05-15T23:59:59",
  "fine_date": "2026-05-01T23:59:59",
  "source_account_branch_identifier": "0001",
  "source_account_number": "12345678-9",
  "debtor_document": "12345678900",
  "debtor_name": "Maria Santos",
  "type_document": "CPF",
  "tag": "Invoice #4567"
}

Fine Types

Response

Both modes return the same response structure. Fields that only apply to charge QR Codes (such as due_date, fine, and fine_date) are returned as null when you generate a simplified QR Code.

{
  "worked": true,
  "pix_copy_and_paste": "00020126580014br.gov.bcb.pix01361234567890123456789012345678901234520400005303986540525.005802BR5925Example Company Name6014CIDADE EXEMPLO62070503***63045ABC",
  "qr_code_id": 98766,
  "debtor_name": "Empresa XYZ Ltda",
  "debtor_document": "12345678000190",
  "type_document": "CNPJ",
  "debtor_institution": null,
  "debtor_institution_number": null,
  "expiration_date": "2026-05-10T23:59:59",
  "due_date": "2026-04-25T23:59:59",
  "amount_chargeback": null,
  "amount": 250.00,
  "fee": 0.00,
  "type_fine": "VALUE",
  "fine": 10.00,
  "fine_date": "2026-04-26T23:59:59",
  "status": "NEW",
  "base_64_image": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAIAAAD2HxkiAAAA...",
  "base_64_image_url": "https://s3.amazonaws.com/qrcodes/1234567890-abc-def-ghi-123456789.png",
  "account_number": "12345678-9",
  "agency_number": "0001",
  "endToEndId": "",
  "payment_date": null,
  "tax": null,
  "tx_id": null,
  "tag": "Invoice #INV-2024-789"
}

Error Responses

Business Rules

Choosing the mode:

Date Validation Rules (Full / Charge QR Code):

• All dates must use the format YYYY-MM-DDTHH:MM:SS.
• All dates must be future dates (cannot be in the past).
• expiration_date must be at least 1 day after due_date.
• fine_date must be at least 1 day after due_date.
• Typical ordering: due_date < fine_date < expiration_date.

Payment Timeline Example (Full / Charge QR Code):

Due Date: April 25
Fine Date: April 26
Expiration: May 10

Payment on April 24: No fine
Payment on April 25: No fine
Payment on April 26 or later: Fine applied
Payment after May 10: QR Code expired, cannot pay

General Validations:

• amount must be greater than 0.
• expiration_date must be a future date in the format YYYY-MM-DDTHH:MM:SS.
• The account must exist and have at least one PIX key registered.
• You must have access to the account.
• The amount must not exceed account/global limits.

Debtor Information:

• Simplified QR Code: optional. Can be provided for tracking only and is not enforced during payment.
• Full / Charge QR Code: required. Used for validation and tracking, and may be used by banks for fraud prevention. Document validation includes check-digit verification.

QR Code Image:

• base_64_image: complete base64 string for direct HTML embedding.
• base_64_image_url: S3 URL for downloading the PNG image.
• Image format: PNG, suitable for display on web or mobile.
• Images are stored for the lifetime of the QR Code.