---
updatedAt: 2026-06-16T12:48:09.000Z
agentTools:
siteIndex: https://developers.pismo.io/llms.txt
projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---
# Create dynamic COBV QR Code
Generate a new COBV QR Code image and EMV (Europay Mastercard Visa) string.
COB is short for *cobranca*, which means *charge* in Portuguese. A COB QR Code has an expiration date while a COBV QR Code has a due date, fine, interest, and rebates.
For more information, refer to [Pix and QR Codes](doc:pix-and-qr-codes).
Typically, this endpoint is used to generate a dynamic QR Code for the [Pix instant payments](doc:pix-instant-payments) system.
**Note:** This endpoint takes an account token - an access token encoded with a Pismo account ID.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Instant payments - QR Code",
"contact": {
"name": "Pismo"
},
"description": "QR Code API for creating dynamic QR Code strings, and payloads for payment",
"license": {
"name": "Copyright Pismo"
},
"version": "1.0"
},
"servers": [
{
"url": "https://sandbox-cdn.pismolabs.io/qrcode",
"description": "Sandbox API server for testing."
}
],
"tags": [
{
"name": "QR Code"
}
],
"components": {
"parameters": {
"authHeader": {
"name": "Authorization",
"in": "header",
"schema": {
"type": "string"
},
"description": "Account token - token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.\n",
"required": true
}
},
"schemas": {
"accessToken": {
"type": "string",
"description": "QR Code access token generated and returned at creation.\n",
"example": "1234567890"
},
"accessTokenRequest": {
"type": "string",
"description": "Access token related to the `url_payload`/`url_payload_rec` fields, used to register and validate a QR code.\n\nThis field **must** be provided if the PSP requires it. The URL format is described in the Manual of Standards for PIX Initiation.\n",
"example": "153ed19a-e738-4417-9e98-a515c276a731"
},
"additionalInfo": {
"type": "array",
"description": "Additional remarks",
"items": {
"$ref": "#/components/schemas/qrcode.Additional"
}
},
"address": {
"type": "string",
"maxLength": 200,
"description": "Location",
"example": "10 Downing Street, London SW1A 2AB, UK"
},
"allowsValueChange": {
"type": "boolean",
"description": "Can payer change payment values? Default is `false`.",
"example": true
},
"charge": {
"description": "Charge information",
"allOf": [
{
"$ref": "#/components/schemas/qrcode.Charge"
}
]
},
"city": {
"type": "string",
"maxLength": 40,
"description": "City where payment occurred.",
"example": "Brasilia"
},
"creationDate": {
"type": "string",
"format": "datetime",
"description": "QR Code creation date/time. RFC 3339 format.",
"example": "2023-04-12T23:20:50.52Z"
},
"customer.DetailMessage": {
"type": "object",
"properties": {
"external": {
"type": "array",
"items": {
"$ref": "#/components/schemas/customer.ExternalMessage"
}
},
"parameters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/customer.ParameterMessage"
}
},
"payload": {
"type": "array",
"items": {
"$ref": "#/components/schemas/customer.PayloadMessage"
}
}
}
},
"customer.Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code.",
"example": "EPT0001"
},
"details": {
"$ref": "#/components/schemas/customer.DetailMessage"
},
"message": {
"type": "string",
"description": "Error message.",
"example": "User not found"
}
}
},
"customer.ExternalMessage": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code.",
"example": "PBE315"
},
"message": {
"type": "string",
"description": "Error message.",
"example": "Generic error"
}
}
},
"customer.ParameterMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Detailed field name",
"example": "query_parameter"
},
"message": {
"type": "string",
"description": "Error's message.",
"example": "Generic error"
}
}
},
"customer.PayloadMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Detailed field name.",
"example": "Entity.field"
},
"message": {
"type": "string",
"description": "Error message.",
"example": "Generic error"
}
}
},
"discountDate": {
"type": "string",
"format": "date",
"description": "Last date discount can be applied. Format = yyyy-mm-dd.",
"example": "2024-01-12"
},
"discountFixedDates": {
"type": "array",
"description": "Maximum dates for payment to apply the discount (fixed value). Use this attribute for `discount_type` = `FIXED_VALUE_UNTIL_THE_DATES_INFORMED`\n",
"items": {
"$ref": "#/components/schemas/qrcode.DiscountDate"
}
},
"discountType": {
"type": "string",
"description": "Discount value type.\n",
"enum": [
"FIXED_VALUE_UNTIL_THE_DATES_INFORMED",
"PERCENTAGE_DATE_REPORTED",
"AMOUNT_PER_CALENDAR_DAY_ADVANCE",
"AMOUNT_ADVANCE_WORKING_DAY",
"PERCENTAGE_ADVANCE_CURRENT_DAY",
"PERCENTAGE_ADVANCE_WORKING_DAY"
],
"example": "FIXED_VALUE_UNTIL_THE_DATES_INFORMED"
},
"discountValue": {
"type": "number",
"description": "Discount value to be applied when `discount_type` is not `FIXED_VALUE_UNTIL_THE_DATES_INFORMED` or `PERCENTAGE_DATE_REPORTED`.\n",
"example": 99
},
"discountValue2": {
"type": "number",
"description": "Discount values.",
"example": 86753.09
},
"documentNumber": {
"type": "string",
"maxLength": 15,
"description": "Government ID, such as a CPF (Cadastro de Pessoas Fisicas - individual tax ID in Brazil) or a CNPJ (Cadastro Nacional de Pessoa Juridica - business tax ID in Brazil) number.\n",
"example": "42761202686"
},
"dueDate": {
"type": "string",
"format": "date",
"description": "Payment due date. Format = yyyy-mm-dd"
},
"emv": {
"type": "string",
"description": "Base 64 encoded discount QR Code payload. EMV = Europay, Mastercard and Visa, a global standard for credit and debit payment. The EMV might include details required for secure transactions such as cardholder informatipn, transaction amount, merchant information, and other relevant data.\n",
"example": "00020101021226980014br.gov.bcb.pix2576api-h.developer.btgpactual.com/pc/p/v2/...***63040441"
},
"externalID": {
"type": "string",
"description": "Client-generated record identifier for client tracking and monitoring.\n",
"example": "my-external-id-9999-6474"
},
"finalAmount": {
"type": "number",
"description": "Total (initial - `settlement_final_amount` - `discount_final_amount` + `interest_final_amount` + `fine_final_amount`)\n",
"example": 10
},
"fineFinalAmount": {
"type": "number",
"description": "Fine total (calculated).",
"example": 99.87
},
"fineType": {
"type": "string",
"description": "Fine type.",
"enum": [
"FIXED_VALUE",
"PERCENT"
],
"example": "FIXED_VALUE"
},
"fineValue": {
"type": "number",
"description": "Fine value.",
"example": 45.67
},
"initialAmount": {
"type": "number",
"description": "Initial payment amount",
"example": 86753.09
},
"interestFinalAmount": {
"type": "number",
"description": "Interest total (calculated).",
"example": 67.89
},
"interestType": {
"type": "string",
"description": "Interest type to calculate.\n",
"enum": [
"VALUE_CALENDAR_DAYS",
"PERCENTAGE_PER_DAY_CALENDAR_DAYS",
"PERCENTAGE_PER_MONTH_CALENDAR_DAYS",
"PERCENTAGE_PER_YEAR_CALENDAR_DAYS",
"VALUE_WORKING_DAYS",
"PERCENTAGE_PER_DAY_WORKING_DAYS",
"PERCENTAGE_PER_MONTH_WORKING_DAYS",
"PERCENTAGE_PER_YEAR_WORKING_DAYS"
],
"example": "VALUE_WORKING_DAYS"
},
"interestValue": {
"type": "number",
"description": "Value to be applied.",
"example": 34.09
},
"jws": {
"type": "string",
"description": "JWS (JSON Web Signature) payload. When a JWT (JSON Web Token) is signed, it becomes a JWS.\n",
"example": "eYqqqwq.heif.jk2w"
},
"labelName": {
"type": "string",
"maxLength": 140,
"description": "Label name",
"example": "Purity of essence"
},
"lastUpdate": {
"type": "string",
"format": "datetime",
"description": "When QR Code last updated. RFC 3339 format.",
"example": "2023-04-12T23:20:50.52Z"
},
"legalType": {
"type": "string",
"description": "Person legal type:\n * `LEGAL_PERSON` - Person\n * `NATURAL_PERSON` - Company or organization\n",
"enum": [
"LEGAL_PERSON",
"NATURAL_PERSON"
],
"example": "NATURAL_PERSON"
},
"locStatus": {
"type": "string",
"description": "QR Code status, in the Pismo standardized enum.",
"enum": [
"ACTIVE",
"COMPLETED",
"REMOVED_BY_PAYEE",
"REMOVED_BY_PSP"
],
"example": "ACTIVE"
},
"merchantCategory": {
"type": "string",
"description": "Receiver ISO 18245 merchant category code.",
"example": "5651"
},
"name": {
"type": "string",
"maxLength": 25,
"description": "Name",
"example": "Eva Destrukion"
},
"payerInfo": {
"allOf": [
{
"$ref": "#/components/schemas/qrcode.Payer"
}
],
"description": "Payer info"
},
"payerSolicitation": {
"type": "string",
"maxLength": 140,
"description": "Payee text sent to payer.",
"example": "For dinner last night"
},
"pixKey": {
"type": "string",
"maxLength": 77,
"description": "Payee Pix key (should have Pismo account)",
"example": "chuck@steaks.com"
},
"qrcode.Additional": {
"type": "object",
"required": [
"name",
"value"
],
"properties": {
"name": {
"$ref": "#/components/schemas/labelName"
},
"value": {
"$ref": "#/components/schemas/value"
}
}
},
"qrcode.Charge": {
"type": "object",
"required": [
"due_date"
],
"properties": {
"due_date": {
"$ref": "#/components/schemas/dueDate"
},
"validity_after_expiration_day": {
"$ref": "#/components/schemas/validityAfterExpirationDay"
},
"discount_type": {
"$ref": "#/components/schemas/discountType"
},
"discount_value": {
"$ref": "#/components/schemas/discountValue"
},
"discount_fixed_dates": {
"$ref": "#/components/schemas/discountFixedDates"
},
"fine_type": {
"$ref": "#/components/schemas/fineType"
},
"fine_value": {
"$ref": "#/components/schemas/fineValue"
},
"fine_final_amount": {
"$ref": "#/components/schemas/fineFinalAmount"
},
"interest_type": {
"$ref": "#/components/schemas/interestType"
},
"interest_value": {
"$ref": "#/components/schemas/interestValue"
},
"interest_final_amount": {
"$ref": "#/components/schemas/interestFinalAmount"
},
"settlement_type": {
"$ref": "#/components/schemas/settlementType"
},
"settlement_value": {
"$ref": "#/components/schemas/settlementValue"
},
"settlement_final_amount": {
"$ref": "#/components/schemas/settlementFinalAmount"
},
"final_amount": {
"$ref": "#/components/schemas/finalAmount"
}
}
},
"qrcode.DiscountDate": {
"type": "object",
"properties": {
"date": {
"$ref": "#/components/schemas/discountDate"
},
"value": {
"$ref": "#/components/schemas/discountValue2"
}
}
},
"qrcodeExpirationTime": {
"type": "integer",
"description": "QR Code's maximum time for presentation (in seconds)",
"example": 7200
},
"qrcodeID": {
"type": "string",
"description": "Pismo QR Code identifier",
"example": "442e992a-2f89-46fb-820a-958693bde84d"
},
"qrcode.imageb64": {
"type": "string",
"description": "Base64 encoded QR Code",
"example": "dfkk7830o*&#)@#9FEE"
},
"qrcode.Location": {
"type": "object",
"description": "Location URL information",
"properties": {
"url_jwk": {
"$ref": "#/components/schemas/urlJWK"
},
"url_payload": {
"$ref": "#/components/schemas/urlPayload"
}
}
},
"qrcode.PayeeRequest": {
"type": "object",
"description": "Payee information",
"required": [
"address",
"city",
"key",
"state",
"zip_code"
],
"properties": {
"address": {
"$ref": "#/components/schemas/address"
},
"city": {
"$ref": "#/components/schemas/city"
},
"key": {
"$ref": "#/components/schemas/pixKey"
},
"state": {
"$ref": "#/components/schemas/state"
},
"zip_code": {
"$ref": "#/components/schemas/zipCode"
},
"category": {
"$ref": "#/components/schemas/merchantCategory"
}
}
},
"qrcode.Payer": {
"type": "object",
"description": "Payer information",
"required": [
"name"
],
"properties": {
"name": {
"$ref": "#/components/schemas/name"
},
"address": {
"$ref": "#/components/schemas/address"
},
"city": {
"$ref": "#/components/schemas/city"
},
"document_number": {
"$ref": "#/components/schemas/documentNumber"
},
"state": {
"$ref": "#/components/schemas/state"
},
"trade_name": {
"$ref": "#/components/schemas/tradeName"
},
"type": {
"$ref": "#/components/schemas/legalType"
},
"zip_code": {
"$ref": "#/components/schemas/zipCode"
}
}
},
"qrcode.QrCodeGenerateCobResponse": {
"type": "object",
"description": "Generate COB Qrcode response",
"required": [
"id",
"access_token",
"external_id",
"status",
"loc_status",
"emv",
"qrcode_image_b64"
],
"properties": {
"id": {
"$ref": "#/components/schemas/qrcodeID"
},
"access_token": {
"$ref": "#/components/schemas/accessToken"
},
"external_id": {
"$ref": "#/components/schemas/externalID"
},
"emv": {
"$ref": "#/components/schemas/emv"
},
"status": {
"$ref": "#/components/schemas/statusDeprecated"
},
"loc_status": {
"$ref": "#/components/schemas/locStatus"
},
"qrcode_image_b64": {
"$ref": "#/components/schemas/qrcode.imageb64"
},
"version": {
"$ref": "#/components/schemas/version"
},
"jws": {
"$ref": "#/components/schemas/jws"
},
"creation_date": {
"$ref": "#/components/schemas/creationDate"
},
"last_update": {
"$ref": "#/components/schemas/lastUpdate"
}
}
},
"qrcode.QrCodeGenerateCobVRequest": {
"type": "object",
"description": "Generate COBV QR Code request",
"required": [
"charge",
"payee",
"payer",
"initial_amount",
"transaction_identification"
],
"properties": {
"charge": {
"$ref": "#/components/schemas/charge"
},
"payee": {
"$ref": "#/components/schemas/qrcode.PayeeRequest"
},
"payer": {
"$ref": "#/components/schemas/payerInfo"
},
"initial_amount": {
"$ref": "#/components/schemas/initialAmount"
},
"transaction_identification": {
"$ref": "#/components/schemas/transactionID"
},
"payer_solicitation": {
"$ref": "#/components/schemas/payerSolicitation"
},
"qrcode_expiration_time": {
"$ref": "#/components/schemas/qrcodeExpirationTime"
},
"reusable": {
"$ref": "#/components/schemas/reusable"
},
"allows_value_change": {
"$ref": "#/components/schemas/allowsValueChange"
},
"location": {
"$ref": "#/components/schemas/qrcode.Location"
},
"additional_information": {
"$ref": "#/components/schemas/additionalInfo"
},
"access_token": {
"$ref": "#/components/schemas/accessTokenRequest"
}
}
},
"reusable": {
"type": "boolean",
"description": "Can QR Code be reused? Default is `false`.",
"default": false,
"example": true
},
"settlementFinalAmount": {
"type": "number",
"description": "Total settlement (calculated as fixed or percentage).",
"example": 876.34
},
"settlementType": {
"type": "string",
"description": "Settlement type.",
"enum": [
"FIXED_VALUE",
"PERCENT"
],
"example": "FIXED_VALUE"
},
"settlementValue": {
"type": "number",
"description": "Settlement value (depends on `settlement_type`).",
"example": 453.98
},
"state": {
"type": "string",
"maxLength": 2,
"description": "Brazilian state where payment will occur - two letter ISO 3166 code.",
"example": "DF"
},
"statusDeprecated": {
"type": "string",
"deprecated": true,
"description": "QR Code status. Deprecated - use `loc_status` instead. Scheduled for removal on 2027-02-14.",
"enum": [
"ACTIVE",
"COMPLETED",
"REMOVED_BY_PAYEE",
"REMOVED_BY_PSP"
],
"example": "ACTIVE"
},
"tradeName": {
"type": "string",
"description": "Company name",
"example": "Acme Widgets"
},
"transactionID": {
"type": "string",
"minLength": 26,
"maxLength": 36,
"description": "Client-generated unique transaction ID for client monitoring and tracking.\n",
"example": "trans-id-75789947401234567"
},
"urlJWK": {
"type": "string",
"description": "PSP Receiver's URL that holds key pairs in JSON format. Should be hosted on the same site associated with the CERTQRC certificate. Use the format \"JWK Set URL\" without the protocol (http/https).\n\nThe Central Bank uses this field and `url_payload` to register and validate the QR Code. This field **must** be passed if the PSP requires it.\n\nThe URL format is described in Manual de Segurança do PIX.\n"
},
"urlPayload": {
"type": "string",
"maxLength": 77,
"description": "PSP Receiver's URL containing the dynamic QR Code's JSON Web Signature (JWS). Should not include the protocol (http/https).\n\nThe Central Bank uses this field and `url_jwk` to register and validate the QR Code. This field **must** be passed if the PSP requires it.\n\nThe URL format is described in Manual de Padrões para Iniciação do PIX.\n",
"example": "example.com/pix/8b3da2f3-941-40d1-a91a-bd93113bd441"
},
"validityAfterExpirationDay": {
"type": "integer",
"description": "How many days QR Code is valid after expiration"
},
"value": {
"type": "string",
"maxLength": 140,
"description": "Value",
"example": "5.00"
},
"version": {
"type": "integer",
"description": "Current version",
"example": 1
},
"zipCode": {
"type": "string",
"description": "Location postal code.",
"example": "8675309"
}
},
"responses": {
"400BadRequest": {
"description": "Bad request",
"headers": {
"x-cid": {
"schema": {
"type": "string"
},
"description": "Request tracking identifier"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
}
}
}
},
"401Unauthorized": {
"description": "Invalid authorization",
"headers": {
"x-cid": {
"schema": {
"type": "string"
},
"description": "Request tracking identifier"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
}
}
}
},
"403Forbidden": {
"description": "Forbidden",
"headers": {
"x-cid": {
"schema": {
"type": "string"
},
"description": "Request tracking identifier"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
}
}
}
},
"404NotFound": {
"description": "Not found",
"headers": {
"x-cid": {
"schema": {
"type": "string"
},
"description": "Request tracking identifier"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
}
}
}
},
"409Conflict": {
"description": "Conflict",
"headers": {
"x-cid": {
"schema": {
"type": "string"
},
"description": "Request tracking identifier"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
}
}
}
},
"429TooManyRequests": {
"description": "Too many reqquests",
"headers": {
"x-cid": {
"schema": {
"type": "string"
},
"description": "Request tracking identifier"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
}
}
}
},
"500InternalServerError": {
"description": "Internal Server Error",
"headers": {
"x-cid": {
"schema": {
"type": "string"
},
"description": "Request tracking identifier"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
}
}
}
},
"502BadGateway": {
"description": "Bad Gateway",
"headers": {
"x-cid": {
"schema": {
"type": "string"
},
"description": "Request tracking identifier"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
}
}
}
},
"504GatewayTimeout": {
"description": "Gateway Timeout",
"headers": {
"x-cid": {
"schema": {
"type": "string"
},
"description": "Request tracking identifier"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
}
}
}
}
}
},
"paths": {
"/v1/pix/qrcode/cobv": {
"post": {
"summary": "Create dynamic COBV QR Code",
"description": "Generate a new COBV QR Code image and EMV (Europay Mastercard Visa) string.\n\nCOB is short for *cobranca*, which means *charge* in Portuguese. A COB QR Code has an expiration date while a COBV QR Code has a due date, fine, interest, and rebates.\n\nFor more information, refer to [Pix and QR Codes](https://developers.pismo.io/pismo-docs/docs/pix-and-qr-codes).\n\nTypically, this endpoint is used to generate a dynamic QR Code for the [Pix instant payments](https://developers.pismo.io/pismo-docs/docs/pix-instant-payments) system.\n\n**Note:** This endpoint takes an account token - an access token encoded with a Pismo account ID.\n",
"operationId": "post-qrcode-cobv",
"tags": [
"QR Code"
],
"parameters": [
{
"$ref": "#/components/parameters/authHeader"
}
],
"requestBody": {
"description": "Update COB QR Code Request Body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/qrcode.QrCodeGenerateCobVRequest"
}
}
}
},
"responses": {
"202": {
"description": "Generate COB QR Code response",
"headers": {
"x-cid": {
"schema": {
"type": "string"
},
"description": "Request tracking identifier"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/qrcode.QrCodeGenerateCobResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"404": {
"$ref": "#/components/responses/404NotFound"
},
"409": {
"$ref": "#/components/responses/409Conflict"
},
"429": {
"$ref": "#/components/responses/429TooManyRequests"
},
"500": {
"$ref": "#/components/responses/500InternalServerError"
},
"502": {
"$ref": "#/components/responses/502BadGateway"
},
"504": {
"$ref": "#/components/responses/504GatewayTimeout"
}
}
}
}
}
}
```