> ## 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 Saque PIX > Cria um novo saque via PIX informando os dados da chave PIX e do titular da conta destino. **Permissão requerida:** `WITHDRAWAL:WRITE` ou `FULL_ACCESS` **Restrição de IP:** Se a credencial tiver uma lista de IPs permitidos configurada, requisições fora dela são rejeitadas com `403`. Recomendado para credenciais com esta permissão. ## OpenAPI ````yaml POST /withdrawals 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: /withdrawals: post: tags: - External API - Withdrawals (Saques) summary: Criar um saque via PIX description: >- Cria um novo saque via PIX informando os dados da chave PIX e do titular da conta destino. **Permissão requerida:** `WITHDRAWAL:WRITE` ou `FULL_ACCESS` **Restrição de IP:** Se a credencial tiver uma lista de IPs permitidos configurada, requisições fora dela são rejeitadas com `403`. Recomendado para credenciais com esta permissão. operationId: ExternalWithdrawalsController_create 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/CreateExternalWithdrawalInput' responses: '201': description: Saque criado com sucesso content: application/json: schema: $ref: '#/components/schemas/GetExternalWithdrawalOutput' '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' '403': description: Forbidden - Permission denied content: application/json: schema: $ref: 032abb87-06b5-4a7b-ab1b-7b9ab3c5ce20 '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: CreateExternalWithdrawalInput: type: object description: >- Dados para criar um saque via PIX. Informe **exatamente um** entre `amount` (valor bruto debitado do saldo) **ou** `netAmount` (valor líquido que o destinatário deve receber). properties: amount: type: number minimum: 1 description: >- Valor **bruto** em BRL debitado do saldo. O destinatário recebe `amount - feeAmount`. Mínimo R$ 1,00. Informe `amount` OU `netAmount` — nunca os dois. example: 150.75 netAmount: type: number minimum: 1 description: >- Valor **líquido** em BRL que o destinatário deve receber. A API calcula o gross necessário (`gross = netAmount + feeAmount`) e debita esse total do saldo. Mínimo R$ 1,00. Informe `amount` OU `netAmount` — nunca os dois. example: 150 pixKey: type: string description: Chave PIX do destinatário. example: '12345678901' pixKeyType: type: string enum: - cpf - cnpj - email - phone - random description: Tipo da chave PIX. example: cpf holderName: type: string description: Nome do titular da conta PIX. example: João da Silva holderDocument: type: string description: CPF ou CNPJ do titular. example: '12345678901' holderDocumentType: type: string enum: - cpf - cnpj description: Tipo do documento do titular. example: cpf externalReference: type: string maxLength: 255 description: >- Seu ID de referência externa (opcional). É devolvido no response e nos webhooks `withdrawal_completed` e `withdrawal_failed` para facilitar a reconciliação com seus sistemas internos. example: saque-empresa-001 required: - pixKey - pixKeyType - holderName - holderDocument - holderDocumentType GetExternalWithdrawalOutput: type: object description: Dados do saque criado. properties: id: type: string format: uuid description: ID do saque example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 amount: type: number description: Valor do saque em BRL example: 150.75 feeAmount: type: number description: Valor da taxa em BRL example: 2.5 netAmount: type: number description: Valor líquido em BRL example: 148.25 status: type: string enum: - pending - processing - completed - failed description: Status do saque example: completed snapshotPixKey: type: string nullable: true description: Chave PIX usada no momento do saque example: '12345678901' snapshotPixKeyType: type: string enum: - cpf - cnpj - email - phone - random nullable: true description: Tipo da chave PIX usada no momento do saque example: cpf snapshotHolderName: type: string description: Nome do titular no momento do saque example: João da Silva snapshotHolderDocument: type: string description: Documento do titular no momento do saque example: '12345678901' failureReason: type: string nullable: true description: Motivo da falha (quando status = failed) example: null pspReference: type: string nullable: true description: Referência do PSP (provedor de pagamento) example: null createdAt: type: string format: date-time description: Data de criação example: '2026-02-10T14:30:00.000Z' processedAt: type: string format: date-time nullable: true description: Data de processamento example: '2026-02-10T14:30:01.000Z' externalReference: type: string nullable: true description: Sua referência externa enviada na criação do saque (opcional) example: saque-empresa-001 required: - id - amount - feeAmount - netAmount - status - snapshotHolderName - snapshotHolderDocument - 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 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Access token obtido no POST /auth (client_id + client_secret). Válido por 300 segundos. ````