> ## Documentation Index > Fetch the complete documentation index at: https://docs.misespay.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar Cobrança PIX > Cria uma cobrança PIX instantânea. **Permissão requerida:** `PIX:WRITE` ou `FULL_ACCESS` ## OpenAPI ````yaml POST /pix openapi: 3.0.0 info: title: MisesPay API description: MisesPay Payment API documentation version: '1.0' contact: {} servers: - url: https://api.misespay.com/v2 security: [] paths: /pix: post: tags: - External API - PIX summary: Criar uma cobrança PIX description: |- Cria uma cobrança PIX instantânea. **Permissão requerida:** `PIX:WRITE` ou `FULL_ACCESS` operationId: ExternalPixController_createCharge parameters: - name: Idempotency-Key in: header required: false description: >- Chave única do cliente (8-255 chars) que torna a requisição idempotente. Retentativas com a mesma chave retornam a resposta cacheada (TTL 24h). Mesma chave com body diferente retorna 422. schema: type: string minLength: 8 maxLength: 255 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePixChargeInput' responses: '201': description: Cobrança PIX criada com sucesso content: application/json: schema: $ref: '#/components/schemas/CreatePixChargeOutput' '400': description: Bad Request - Validation error content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: Unauthorized - Authentication required content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: Not Found - Resource not found content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' security: - bearerAuth: [] components: schemas: CreatePixChargeInput: type: object properties: amount: type: number description: 'Valor em BRL (ex: 100.50 para R$ 100,50)' minimum: 1 example: 150.75 description: type: string description: Descrição da cobrança maxLength: 255 example: 'Pagamento do pedido #12345' customer: description: Dados do pagador (todos opcionais). allOf: - $ref: '#/components/schemas/CustomerDto' projectId: type: string description: ID do projeto para associar a transação format: uuid expiresIn: type: integer description: 'Segundos até expiração (padrão: 86400 = 24h)' minimum: 300 maximum: 604800 example: 3600 externalReference: type: string description: Seu ID de referência externa maxLength: 255 example: pedido-12345 metadata: type: object description: Metadados customizados (pares chave-valor) additionalProperties: true example: orderId: '12345' source: website required: - amount - description CreatePixChargeOutput: type: object properties: id: type: string description: ID da cobrança (ID da transação) format: uuid status: type: string description: Status da cobrança enum: - pending - completed - failed - cancelled amount: type: number description: Valor em BRL example: 150.75 currency: type: string description: Código da moeda example: BRL pixCopyPaste: type: string description: Código PIX copia e cola example: 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890 qrCodeBase64: type: string description: QR Code do PIX em formato data URI (data:image/png;base64,...) pspPaymentId: type: string description: >- ID da transação no provedor de pagamento (PSP). Use para conciliação; ausente se o PSP não retornou o ID na criação. example: de3516a2-c63a-4c02-b132-a239bf42e183 expiresAt: type: string description: Data de expiração format: date-time externalReference: type: string description: Seu ID de referência externa example: pedido-12345 createdAt: type: string description: Data de criação format: date-time required: - id - status - amount - currency - pixCopyPaste - expiresAt - createdAt BadRequestErrorResponse: type: object properties: statusCode: type: number example: 400 error: type: string example: BadRequest message: type: string example: name must be longer than or equal to 2 characters details: type: object timestamp: type: string example: '2025-12-15T22:00:00.000Z' traceId: type: string required: - statusCode - error - message - timestamp UnauthorizedErrorResponse: type: object properties: statusCode: type: number example: 401 error: type: string example: Unauthorized message: type: string example: Authentication token is required details: type: object timestamp: type: string example: '2025-12-15T22:00:00.000Z' traceId: type: string required: - statusCode - error - message - timestamp NotFoundErrorResponse: type: object properties: statusCode: type: number example: 404 error: type: string example: NotFound message: type: string example: Resource with id 550e8400-e29b-41d4-a716-446655440000 not found details: type: object example: resource: Example id: 550e8400-e29b-41d4-a716-446655440000 timestamp: type: string example: '2025-12-15T22:00:00.000Z' traceId: type: string required: - statusCode - error - message - timestamp InternalServerErrorResponse: type: object properties: statusCode: type: number example: 500 error: type: string example: InternalError message: type: string example: An unexpected error occurred details: type: object timestamp: type: string example: '2025-12-15T22:00:00.000Z' traceId: type: string example: 2771463d58840c8e116dc6dda1e1e5d0 required: - statusCode - error - message - timestamp CustomerDto: type: object properties: name: type: string description: Nome do pagador maxLength: 255 example: João da Silva document: type: string description: CPF ou CNPJ do pagador, apenas números (opcional) maxLength: 20 example: '12345678909' email: type: string description: E-mail do pagador format: email maxLength: 255 phone: type: string description: Telefone do pagador (formato livre) maxLength: 20 example: '+5511999998888' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Access token obtido no POST /auth (client_id + client_secret). Válido por 300 segundos. ````