---
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 COB QR Code

Generate a new dynamic COB QR Code 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 <b>401 Unauthorized</b> 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"
      },
      "agentModalityChange": {
        "type": "string",
        "description": "Agent providing withdrawal change service",
        "enum": [
          "AGTEC",
          "AGTOT"
        ],
        "example": "AGTEC"
      },
      "agentModalityWithdraw": {
        "type": "string",
        "description": "Agent providing withdrawal service",
        "enum": [
          "AGTEC",
          "AGTOT",
          "AGPSS"
        ],
        "example": "AGTEC"
      },
      "allowsValueChange": {
        "type": "boolean",
        "description": "Can payer change payment values? Default is `false`.",
        "example": true
      },
      "amount": {
        "type": "number",
        "description": "Amount to be transferred.",
        "example": 1050.44
      },
      "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"
          }
        }
      },
      "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"
      },
      "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"
      },
      "initialAmount": {
        "type": "number",
        "description": "Initial payment amount",
        "example": 86753.09
      },
      "ispb": {
        "type": "string",
        "format": "string",
        "description": "Withdrawal/change service provider's ISPB ID",
        "example": "12345678",
        "maxLength": 8
      },
      "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.Change": {
        "type": "object",
        "description": "Change information",
        "required": [
          "agent_modality",
          "ispb_service_provider",
          "amount"
        ],
        "properties": {
          "agent_modality": {
            "$ref": "#/components/schemas/agentModalityChange"
          },
          "ispb_service_provider": {
            "$ref": "#/components/schemas/ispb"
          },
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "allows_value_change": {
            "$ref": "#/components/schemas/allowsValueChange"
          }
        }
      },
      "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.QrCodeGenerateCobRequest": {
        "type": "object",
        "description": "Generate COB QR Code request",
        "required": [
          "payee",
          "payer",
          "transaction_identification",
          "initial_amount"
        ],
        "properties": {
          "payee": {
            "$ref": "#/components/schemas/qrcode.PayeeRequest"
          },
          "payer": {
            "$ref": "#/components/schemas/payerInfo"
          },
          "transaction_identification": {
            "$ref": "#/components/schemas/transactionID"
          },
          "initial_amount": {
            "$ref": "#/components/schemas/initialAmount"
          },
          "payer_solicitation": {
            "$ref": "#/components/schemas/payerSolicitation"
          },
          "qrcode_expiration_time": {
            "$ref": "#/components/schemas/qrcodeExpirationTime"
          },
          "allows_value_change": {
            "$ref": "#/components/schemas/allowsValueChange"
          },
          "reusable": {
            "$ref": "#/components/schemas/reusable"
          },
          "location": {
            "$ref": "#/components/schemas/qrcode.Location"
          },
          "additional_information": {
            "$ref": "#/components/schemas/additionalInfo"
          },
          "access_token": {
            "$ref": "#/components/schemas/accessTokenRequest"
          },
          "withdraw": {
            "$ref": "#/components/schemas/qrcode.Withdraw"
          },
          "change": {
            "$ref": "#/components/schemas/qrcode.Change"
          }
        }
      },
      "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.Withdraw": {
        "type": "object",
        "description": "Withdrawal information",
        "required": [
          "agent_modality",
          "ispb_service_provider",
          "amount"
        ],
        "properties": {
          "agent_modality": {
            "$ref": "#/components/schemas/agentModalityWithdraw"
          },
          "ispb_service_provider": {
            "$ref": "#/components/schemas/ispb"
          },
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "allows_value_change": {
            "$ref": "#/components/schemas/allowsValueChange"
          }
        }
      },
      "reusable": {
        "type": "boolean",
        "description": "Can QR Code be reused? Default is `false`.",
        "default": false,
        "example": true
      },
      "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 <a href=\"https://www.bcb.gov.br/content/estabilidadefinanceira/cedsfn/Manual_de_Seguranca_PIX.pdf\" target=\"_blank\">Manual de Segurança do PIX</a>.\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 <a href=\"https://www.bcb.gov.br/content/estabilidadefinanceira/pix/Regulamento_Pix/II_ManualdePadroesparaIniciacaodoPix.pdf\" target=\"_blank\">Manual de Padrões para Iniciação do PIX</a>.\n",
        "example": "example.com/pix/8b3da2f3-941-40d1-a91a-bd93113bd441"
      },
      "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/cob": {
      "post": {
        "summary": "Create dynamic COB QR Code",
        "description": "Generate a new dynamic COB QR Code 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-create-cob",
        "tags": [
          "QR Code"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/authHeader"
          }
        ],
        "requestBody": {
          "description": "Create COB QR Code Request Body",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/qrcode.QrCodeGenerateCobRequest"
              }
            }
          },
          "required": true
        },
        "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"
          }
        }
      }
    }
  }
}
```