{ "openapi": "3.1.0", "info": { "version": "1.8.0", "title": "PayZu Pix API", "description": "API REST para operações Pix na plataforma PayZu, depósitos, saques, transferências internas, infrações, relatórios e inspeção de callback. Todos os valores estão em BRL (reais), salvo indicação explícita. A autenticação usa um token Bearer emitido durante o onboarding.\n\n## SDKs oficiais\n\n- Node.js: `npm install payzu-pix`\n- Python: `pip install payzu-pix`\n- Go: `go get github.com/PayZuAI/payzu-sdks/go`\n- PHP: client gerado em https://github.com/PayZuAI/payzu-sdks/tree/main/php (sem pacote publicado)\n\nRepo: https://github.com/PayZuAI/payzu-sdks\n", "contact": { "name": "Suporte PayZu", "url": "https://suporte.payzu.com.br" } }, "servers": [ { "url": "https://api.payzu.processamento.com/v1", "description": "Produção" } ], "tags": [ { "name": "Pix Operations", "description": "Crie e gerencie cobranças Pix (depósitos)" }, { "name": "Refunds", "description": "Devolução (estorno) de cobranças Pix recebidas, total ou parcial" }, { "name": "Withdrawals", "description": "Envie dinheiro via Pix (cash out) por chave Pix ou QR Code" }, { "name": "Keys and DICT", "description": "Consulte chaves Pix no diretório DICT e decodifique QR Codes Pix antes de pagar" }, { "name": "Internal Transfer", "description": "Transfira fundos entre contas PayZu (gratuito, instantâneo)" }, { "name": "Account", "description": "Perfil da conta, saldo" }, { "name": "Reports", "description": "Histórico de transações, relatórios, extratos bancários e depósitos pendentes" }, { "name": "Callbacks", "description": "Inspeção e reenvio de callback de webhook" }, { "name": "Webhooks", "description": "Cadastre e gerencie os endpoints de webhook que recebem as notificações de transação" }, { "name": "Infractions", "description": "Gerencie infrações Pix (disputas, denúncias de fraude) e envie defesas" } ], "paths": { "/pix": { "post": { "summary": "Criar Cobrança (depósito Pix)", "description": "Crie um novo **depósito** Pix (cobrança). Retorna o QR Code e os detalhes da transação.", "operationId": "post_pix", "tags": [ "Pix Operations" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostPixRequest" } } } }, "responses": { "200": { "description": "Cobrança criada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "created": { "summary": "Criada (PENDING)", "value": { "id": "PAYZU20260811R4TZ8WD1NC000000", "status": "PENDING", "amount": 10, "type": "DEPOSIT", "qrCodeText": "00020126870014br.gov.bcb.pix2565qrcode.payzu.com.br/dynamic/11111111-2222-3333-4444-5555555555555204000053039865802BR5908PAYZUPLUS6009SAO PAULO62070503***63047EE4", "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQCAYAAAC...", "qrCodeUrl": "https://pix.payzu.com.br/v1/pix/qr-code/PAYZU20260811R4TZ8WD1NC000000", "generatedName": "John Doe", "generatedDocument": "12345678901", "generatedEmail": "john.doe@example.com", "serviceFeeCharged": 0.075, "payerName": null, "payerDocument": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "payerAccountNumber": null, "receiverName": null, "receiverDocument": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "receiverAccountNumber": "000000", "endToEndId": null, "createdAt": "2026-08-11T21:59:11.579Z", "updatedAt": "2026-08-11T21:59:11.579Z", "paidAt": null, "withdrawPixKey": null, "withdrawPixType": null, "clientReference": "order_12345", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "amount", "message": "Too small: expected number to be >=1" } ] } }, "PZD600": { "summary": "O valor mínimo do depósito é R$ 1,00.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZD600", "message": "O valor mínimo do depósito é R$ 1,00.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZD601": { "summary": "O valor máximo do depósito é R$ 50.000,00.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZD601", "message": "O valor máximo do depósito é R$ 50.000,00.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZD602": { "summary": "Para depósitos acima de {limite} é obrigatório informar o documento.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZD602", "message": "Para depósitos acima de {limite} é obrigatório informar o documento.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA200": { "summary": "Forbidden", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA200", "message": "Forbidden", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Operação recusada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZD200": { "summary": "Depósito não permitido para esta conta.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZD200", "message": "Depósito não permitido para esta conta.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "424": { "description": "Falha na instituição financeira", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZD100": { "summary": "Não foi possível gerar o depósito junto à instituição financeira. Tente novam...", "value": { "status": "ERROR", "error": "Failed Dependency", "errorCode": "PZD100", "message": "Não foi possível gerar o depósito junto à instituição financeira. Tente novamente.", "statusCode": 424, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZD103": { "summary": "O tempo limite de processamento do depósito foi atingido. Tente novamente.", "value": { "status": "ERROR", "error": "Failed Dependency", "errorCode": "PZD103", "message": "O tempo limite de processamento do depósito foi atingido. Tente novamente.", "statusCode": 424, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZD500": { "summary": "Nenhuma instituição financeira disponível no momento. Tente novamente em inst...", "value": { "status": "ERROR", "error": "Failed Dependency", "errorCode": "PZD500", "message": "Nenhuma instituição financeira disponível no momento. Tente novamente em instantes.", "statusCode": 424, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "retryAfterSeconds": 5 } } } } } } }, "parameters": [], "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/pix' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"amount\": 10.9,\n \"callbackUrl\": \"https://webhook.cool/\",\n \"generatedName\": \"John Doe\",\n \"generatedEmail\": \"john.doe@example.com\",\n \"generatedDocument\": \"12345678901\",\n \"expiresIn\": 600,\n \"clientReference\": \"order_12345\",\n \"virtualAccount\": \"loja-centro-01\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "import { PayZu } from 'payzu-pix';\n\nconst payzu = new PayZu({ token: process.env.PAYZU_TOKEN });\n\nconst charge = await payzu.pix.create({\n amount: 10.9,\n callbackUrl: 'https://webhook.cool/',\n generatedName: 'John Doe',\n generatedEmail: 'john.doe@example.com',\n generatedDocument: '12345678901',\n expiresIn: 600,\n clientReference: 'order_12345',\n virtualAccount: 'loja-centro-01'\n});\n\nconsole.log(charge.id, charge.status, charge.qrCodeText);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport payzu_pix\n\nconfig = payzu_pix.Configuration(\n host='https://api.payzu.processamento.com/v1',\n access_token=os.environ['PAYZU_TOKEN'],\n)\n\nwith payzu_pix.ApiClient(config) as client:\n api = payzu_pix.PixOperationsApi(client)\n request = payzu_pix.PostPixRequest(\n amount=10.9,\n callback_url='https://webhook.cool/',\n generated_name='John Doe',\n generated_email='john.doe@example.com',\n generated_document='12345678901',\n expires_in=600,\n client_reference='order_12345',\n virtual_account='loja-centro-01',\n )\n charge = api.post_pix(request)\n print(charge.id, charge.status, charge.qr_code_text)" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/receive-pix", "description": "Receber pagamento Pix" } }, "get": { "summary": "Recuperar Cobrança", "description": "Obtém o status e os detalhes mais recentes de um **depósito (cobrança)** Pix. Informe pelo menos um dentre `id`, `clientReference` ou `endToEndId` (`virtualAccount` também é aceito). Ao informar mais de um parâmetro, todos são combinados como filtros (AND).", "operationId": "get_pix", "tags": [ "Pix Operations" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "id", "required": false, "description": "ID da transação.", "schema": { "type": "string" }, "example": "PAYZU20260811R4TZ8WD1NC000000" }, { "in": "query", "name": "clientReference", "required": false, "description": "Referência externa fornecida na criação da cobrança.", "schema": { "type": "string", "maxLength": 64 }, "example": "order_12345" }, { "in": "query", "name": "endToEndId", "required": false, "description": "ID end-to-end do Pix.", "schema": { "type": "string" }, "example": "E00000000202508172159kZ8dQ2mNb1x" }, { "name": "virtualAccount", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "Subconta usada na criação.", "example": "loja-centro-01" } ], "responses": { "200": { "description": "Estado atual da transação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "pending": { "summary": "Pagamento pendente", "value": { "id": "PAYZU20260811R4TZ8WD1NC000000", "status": "PENDING", "amount": 10, "type": "DEPOSIT", "qrCodeText": "00020126870014br.gov.bcb.pix2565qrcode.payzu.com.br/dynamic/11111111-2222-3333-4444-5555555555555204000053039865802BR5908PAYZUPLUS6009SAO PAULO62070503***63047EE4", "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQCAYAAAC...", "qrCodeUrl": "https://pix.payzu.com.br/v1/pix/qr-code/PAYZU20260811R4TZ8WD1NC000000", "generatedName": "John Doe", "generatedDocument": "12345678901", "generatedEmail": "john.doe@example.com", "serviceFeeCharged": 0.075, "payerName": null, "payerDocument": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "payerAccountNumber": null, "receiverName": null, "receiverDocument": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "receiverAccountNumber": "000000", "endToEndId": null, "createdAt": "2026-08-11T21:59:11.579Z", "updatedAt": "2026-08-11T21:59:11.579Z", "paidAt": null, "withdrawPixKey": null, "withdrawPixType": null, "clientReference": "order_12345", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } }, "completed": { "summary": "Pagamento concluído", "value": { "id": "PAYZU20260811R4TZ8WD1NC000000", "status": "COMPLETED", "amount": 10, "type": "DEPOSIT", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": "John Doe", "generatedDocument": "12345678901", "generatedEmail": "john.doe@example.com", "serviceFeeCharged": 0.075, "payerName": "John Doe", "payerDocument": "12345678901", "payerInstitutionIspb": "12345678", "payerInstitutionName": "Banco X", "payerAccountNumber": null, "receiverName": "PayZu Pagamentos Ltda", "receiverDocument": "12.345.678/0001-00", "receiverInstitutionIspb": "23066240", "receiverInstitutionName": "PAYZU IP LTDA.", "receiverAccountNumber": "000000", "endToEndId": "E123456782026081122013B13DMS72H9", "createdAt": "2026-08-11T21:59:11.579Z", "updatedAt": "2026-08-11T22:01:30.123Z", "paidAt": "2026-08-11T22:01:30.123Z", "withdrawPixKey": null, "withdrawPixType": null, "clientReference": "order_12345", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "", "message": "É necessário fornecer 'id', 'clientReference', 'endToEndId' ou 'virtualAccount'" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA200": { "summary": "Forbidden", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA200", "message": "Forbidden", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZC310": { "summary": "Transação não encontrada.", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZC310", "message": "Transação não encontrada.", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/pix' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/pix';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/pix',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/receive-pix", "description": "Receber pagamento Pix" } } }, "/pix/key": { "get": { "summary": "Consulta de chave Pix no DICT", "description": "Consulta o DICT (Diretório de Identificadores de Contas Transacionais) para obter informações sobre uma chave Pix antes de enviar um pagamento. Retorna os dados do titular da chave e a instituição financeira associada.", "operationId": "get_pix_key", "tags": [ "Keys and DICT" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "pixKey", "required": true, "description": "A chave Pix a consultar (CPF, CNPJ, email, telefone ou EVP).", "schema": { "type": "string", "maxLength": 77, "minLength": 1 }, "example": "example@payzu.com.br" } ], "responses": { "200": { "description": "Chave Pix encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixKeyInfo" }, "examples": { "pj": { "summary": "Pessoa Jurídica (PJ)", "value": { "pixKey": "5c8999e2-6b29-468b-b4e9-04d4872b1bc4", "document": "**.345.678/****-**", "name": "EMPRESA EXEMPLO LTDA", "branch": "****", "accountNumber": "*******", "personType": "PJ", "accountType": "CACC", "institutionIspb": "12345678", "institutionCode": "001", "institutionName": "BANCO EXEMPLO S.A." } }, "pf": { "summary": "Pessoa Física (PF)", "value": { "pixKey": "12345678901", "document": "***.456.789-**", "name": "João da Silva", "branch": "****", "accountNumber": "********", "personType": "PF", "accountType": "TRAN", "institutionIspb": "87654321", "institutionCode": "260", "institutionName": "BANCO FICTICIO S.A." } } } } } }, "400": { "description": "Formato de chave Pix inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "pixKey", "message": "Chave PIX inválida. Formatos aceitos: CPF, CNPJ, Email, Telefone (+5511999999999) ou EVP (UUID)" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZK400": { "summary": "Consulta de chave Pix não habilitada para o usuário.", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZK400", "message": "Consulta de chave Pix não habilitada para o usuário.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA200": { "summary": "Forbidden", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA200", "message": "Forbidden", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Chave Pix não encontrada no DICT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZK300": { "summary": "Chave Pix não encontrada.", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZK300", "message": "Chave Pix não encontrada.", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Operação recusada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZK200": { "summary": "Chave Pix inválida.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZK200", "message": "Chave Pix inválida.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "424": { "description": "Falha na instituição financeira", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZI110": { "summary": "Erro de comunicação com a instituição financeira.", "value": { "status": "ERROR", "error": "Failed Dependency", "errorCode": "PZI110", "message": "Erro de comunicação com a instituição financeira.", "statusCode": 424, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZI111": { "summary": "A instituição financeira demorou para responder. Tente novamente.", "value": { "status": "ERROR", "error": "Failed Dependency", "errorCode": "PZI111", "message": "A instituição financeira demorou para responder. Tente novamente.", "statusCode": 424, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "429": { "description": "Limite de requisições excedido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG429": { "summary": "Limite de consultas atingido. Tente novamente em breve. Tente novamente em 30s.", "value": { "status": "ERROR", "error": "Too Many Requests", "errorCode": "PZG429", "message": "Limite de consultas atingido. Tente novamente em breve. Tente novamente em 30s.", "statusCode": 429, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "retryAfterSeconds": 30 } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZI101": { "summary": "Operação não suportada para esta instituição financeira.", "value": { "status": "ERROR", "error": "Internal Server Error", "errorCode": "PZI101", "message": "Operação não suportada para esta instituição financeira.", "statusCode": 500, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/pix/key?pixKey=example%40payzu.com.br' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/pix/key?pixKey=example%40payzu.com.br';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/pix/key?pixKey=example%40payzu.com.br',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/receive-pix", "description": "Receber pagamento Pix" } } }, "/pix/qrcode/read": { "post": { "summary": "Ler QR Code", "description": "Decodifica e extrai informações de um QR Code Pix (formato EMV) antes de efetuar um pagamento. Retorna os dados interpretados, incluindo detalhes do recebedor, valor (se presente) e outros metadados do QR Code. PayZu processa QR Code dinâmico e estático.", "operationId": "post_pix_qrcode_read", "tags": [ "Keys and DICT" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostPixQrcodeReadRequest" } } } }, "responses": { "200": { "description": "QR Code decodificado com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QRCodeReadResponse" }, "examples": { "dynamic": { "summary": "QR Code dinâmico", "value": { "qrCodeType": "DYNAMIC", "name": "LOJA EXEMPLO LTDA", "document": "12345678000199", "amount": 10, "originalAmount": 10, "txid": "c5886b83f0254d0dbfc3900f72d5a8d1", "additionalInfo": null, "expiresIn": 1799, "createdAt": "2026-02-03T22:59:36.138" } }, "static": { "summary": "QR Code estático", "value": { "qrCodeType": "STATIC", "name": "MARIA SANTOS", "document": "98765432100", "amount": 1, "originalAmount": 1, "txid": "QRTEST20251103083119867", "additionalInfo": null, "expiresIn": 0, "createdAt": null } } } } } }, "400": { "description": "Formato de QR Code inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "emv", "message": "Too small: expected string to have >=1 characters" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZK401": { "summary": "Leitura de QR Code não habilitada para o usuário.", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZK401", "message": "Leitura de QR Code não habilitada para o usuário.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA200": { "summary": "Forbidden", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA200", "message": "Forbidden", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "424": { "description": "Falha na instituição financeira", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZI110": { "summary": "Erro de comunicação com a instituição financeira.", "value": { "status": "ERROR", "error": "Failed Dependency", "errorCode": "PZI110", "message": "Erro de comunicação com a instituição financeira.", "statusCode": 424, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "429": { "description": "Limite de requisições excedido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG429": { "summary": "Limite de consultas atingido. Tente novamente em breve. Tente novamente em 30s.", "value": { "status": "ERROR", "error": "Too Many Requests", "errorCode": "PZG429", "message": "Limite de consultas atingido. Tente novamente em breve. Tente novamente em 30s.", "statusCode": 429, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "retryAfterSeconds": 30 } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZI101": { "summary": "Operação não suportada para esta instituição financeira.", "value": { "status": "ERROR", "error": "Internal Server Error", "errorCode": "PZI101", "message": "Operação não suportada para esta instituição financeira.", "statusCode": 500, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "parameters": [], "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/pix/qrcode/read' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"emv\": \"00020101021226770014br.gov.bcb.pix2555api.payzu/pix/qr/v2/013318d6-2d7d-479e-8bb3-b5c7b9da688c5204000053039865802BR5916PAYZU 6007SAOPAULO6217051320260118278956304EC55\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/pix/qrcode/read';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n emv: '00020101021226770014br.gov.bcb.pix2555api.payzu/pix/qr/v2/013318d6-2d7d-479e-8bb3-b5c7b9da688c5204000053039865802BR5916PAYZU 6007SAOPAULO6217051320260118278956304EC55'\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/pix/qrcode/read',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'emv': '00020101021226770014br.gov.bcb.pix2555api.payzu/pix/qr/v2/013318d6-2d7d-479e-8bb3-b5c7b9da688c5204000053039865802BR5916PAYZU 6007SAOPAULO6217051320260118278956304EC55'\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/receive-pix", "description": "Receber pagamento Pix" } } }, "/proof/{id}": { "get": { "summary": "Obter comprovante da transação", "description": "Retorna o comprovante da transação como JSON com o campo `base64` (PDF codificado). Decodifique para exibir ou salvar como `.pdf`.", "operationId": "get_proof", "tags": [ "Pix Operations" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "ID da transação.", "schema": { "type": "string" }, "example": "PAYZU20260814T6NX1CV9MK000000" }, { "in": "query", "name": "type", "required": false, "description": "Formato de retorno.", "schema": { "type": "string", "enum": [ "pdf", "base64" ], "default": "pdf" }, "example": "pdf" } ], "responses": { "200": { "description": "Comprovante em PDF ou base64", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofResponse" }, "examples": { "base64": { "summary": "Como Base64", "value": { "base64": "JVBERi0xLjQKJ..." } } } }, "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "PDF binário (formato padrão, quando `type=pdf`)." } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "type", "message": "Invalid option: expected one of \"base64\"|\"pdf\"" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Transação não encontrada", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Transação não encontrada", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Operação recusada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZC320": { "summary": "Transação ainda não processada.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZC320", "message": "Transação ainda não processada.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZC321": { "summary": "Comprovante indisponível: transação cancelada sem documento.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZC321", "message": "Comprovante indisponível: transação cancelada sem documento.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZI103": { "summary": "Dado interno ausente para concluir a operação.", "value": { "status": "ERROR", "error": "Internal Server Error", "errorCode": "PZI103", "message": "Dado interno ausente para concluir a operação.", "statusCode": 500, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/proof/PAYZU20260814T6NX1CV9MK000000' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/proof/PAYZU20260814T6NX1CV9MK000000';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/proof/PAYZU20260814T6NX1CV9MK000000',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/receive-pix", "description": "Receber pagamento Pix" } } }, "/withdraw": { "post": { "summary": "Criar saque (chave Pix)", "description": "Envie um **cash out** Pix para a chave Pix especificada.", "operationId": "post_withdraw", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostWithdrawRequest" } } } }, "responses": { "200": { "description": "Saque criado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "created": { "summary": "Criada (PENDING)", "value": { "id": "PAYZU20260817B3PL8SG5WQ000000", "status": "PENDING", "amount": 2, "type": "WITHDRAW", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "payerName": null, "payerDocument": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "payerAccountNumber": "000000", "serviceFeeCharged": 1, "withdrawPixKey": "teste@teste.com", "withdrawPixType": "email", "receiverName": null, "receiverDocument": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "receiverAccountNumber": null, "endToEndId": null, "createdAt": "2026-08-11T21:51:29.748Z", "updatedAt": "2026-08-11T21:51:29.748Z", "paidAt": null, "clientReference": "withdraw_98765", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } }, "completed": { "summary": "Concluído", "value": { "id": "PAYZU20260817B3PL8SG5WQ000000", "status": "COMPLETED", "amount": 2, "type": "WITHDRAW", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "serviceFeeCharged": 1, "payerName": "PayZu Pagamentos Ltda", "payerDocument": "12.345.678/0001-00", "payerInstitutionIspb": "23066240", "payerInstitutionName": "PAYZU IP LTDA.", "payerAccountNumber": "000000", "withdrawPixKey": "teste@teste.com", "withdrawPixType": "email", "receiverName": "Maria Santos", "receiverDocument": "12345678901", "receiverInstitutionIspb": "87654321", "receiverInstitutionName": "Banco Y", "receiverAccountNumber": null, "endToEndId": "E2306624020251217134500X98765432", "createdAt": "2026-08-11T21:51:29.748Z", "updatedAt": "2026-08-11T21:52:15.123Z", "paidAt": "2026-08-11T21:52:15.123Z", "clientReference": "withdraw_98765", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "pixKey", "message": "Invalid input: expected string, received undefined" } ] } }, "PZS600": { "summary": "O valor mínimo do saque é R$ 1,00.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZS600", "message": "O valor mínimo do saque é R$ 1,00.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZS601": { "summary": "O valor máximo do saque é R$ 50.000,00.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZS601", "message": "O valor máximo do saque é R$ 50.000,00.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZS602": { "summary": "O valor do saque está fora dos limites da instituição financeira.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZS602", "message": "O valor do saque está fora dos limites da instituição financeira.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA200": { "summary": "Forbidden", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA200", "message": "Forbidden", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA203": { "summary": "Acesso não permitido a partir deste endereço de IP.", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA203", "message": "Acesso não permitido a partir deste endereço de IP.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA205": { "summary": "Nenhum endereço de IP cadastrado na whitelist. Cadastre o IP de origem antes ...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA205", "message": "Nenhum endereço de IP cadastrado na whitelist. Cadastre o IP de origem antes de operar.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Operação recusada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZS200": { "summary": "Saque não permitido para esta conta no momento.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZS200", "message": "Saque não permitido para esta conta no momento.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "424": { "description": "Falha na instituição financeira", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZS500": { "summary": "Nenhuma instituição financeira disponível para o saque no momento. Tente nova...", "value": { "status": "ERROR", "error": "Failed Dependency", "errorCode": "PZS500", "message": "Nenhuma instituição financeira disponível para o saque no momento. Tente novamente em instantes.", "statusCode": 424, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "retryAfterSeconds": 5 } } } } } } }, "parameters": [], "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/withdraw' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"amount\": 2,\n \"pixKey\": \"teste@teste.com\",\n \"pixType\": \"email\",\n \"callbackUrl\": \"https://webhook.cool/\",\n \"clientReference\": \"withdraw_98765\",\n \"description\": \"Weekly payout\",\n \"virtualAccount\": \"loja-centro-01\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/withdraw';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n amount: 2,\n pixKey: 'teste@teste.com',\n pixType: 'email',\n callbackUrl: 'https://webhook.cool/',\n clientReference: 'withdraw_98765',\n description: 'Weekly payout',\n virtualAccount: 'loja-centro-01'\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/withdraw',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'amount': 2,\n 'pixKey': 'teste@teste.com',\n 'pixType': 'email',\n 'callbackUrl': 'https://webhook.cool/',\n 'clientReference': 'withdraw_98765',\n 'description': 'Weekly payout',\n 'virtualAccount': 'loja-centro-01'\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/send-pix", "description": "Enviar Pix" } }, "get": { "summary": "Consultar Saque", "description": "Retorna o status e os detalhes atuais de um saque. Informe pelo menos um destes parâmetros: `id`, `clientReference` ou `endToEndId`. Se informar mais de um, todos são aplicados como filtro (AND), o que pode não retornar registro caso não apontem para a mesma transação.", "operationId": "get_withdraw", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "id", "required": false, "description": "ID da transação.", "schema": { "type": "string" }, "example": "PAYZU20260817B3PL8SG5WQ000000" }, { "in": "query", "name": "clientReference", "required": false, "description": "Referência externa informada na criação do saque.", "schema": { "type": "string", "maxLength": 64 }, "example": "order_12345" }, { "in": "query", "name": "endToEndId", "required": false, "description": "ID end-to-end do Pix.", "schema": { "type": "string" }, "example": "E00000000202508172159kZ8dQ2mNb1x" }, { "name": "virtualAccount", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "Subconta usada na criação.", "example": "loja-centro-01" } ], "responses": { "200": { "description": "Estado atual do saque", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "pending": { "summary": "Saque pendente", "value": { "id": "PAYZU20260817B3PL8SG5WQ000000", "status": "PENDING", "amount": 2, "type": "WITHDRAW", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "payerName": null, "payerDocument": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "payerAccountNumber": "000000", "serviceFeeCharged": 1, "withdrawPixKey": "teste@teste.com", "withdrawPixType": "email", "receiverName": null, "receiverDocument": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "receiverAccountNumber": null, "endToEndId": null, "createdAt": "2026-08-11T21:51:29.748Z", "updatedAt": "2026-08-11T21:51:29.748Z", "paidAt": null, "clientReference": "withdraw_98765", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } }, "completed": { "summary": "Saque concluído", "value": { "id": "PAYZU20260817B3PL8SG5WQ000000", "status": "COMPLETED", "amount": 2, "type": "WITHDRAW", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "serviceFeeCharged": 1, "payerName": "PayZu Pagamentos Ltda", "payerDocument": "12.345.678/0001-00", "payerInstitutionIspb": "23066240", "payerInstitutionName": "PAYZU IP LTDA.", "payerAccountNumber": "000000", "withdrawPixKey": "teste@teste.com", "withdrawPixType": "email", "receiverName": "Maria Santos", "receiverDocument": "12345678901", "receiverInstitutionIspb": "87654321", "receiverInstitutionName": "Banco Y", "receiverAccountNumber": null, "endToEndId": "E2306624020251217134500X98765432", "createdAt": "2026-08-11T21:51:29.748Z", "updatedAt": "2026-08-11T21:52:15.123Z", "paidAt": "2026-08-11T21:52:15.123Z", "clientReference": "withdraw_98765", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "", "message": "É necessário fornecer 'id', 'clientReference', 'endToEndId' ou 'virtualAccount'" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA200": { "summary": "Forbidden", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA200", "message": "Forbidden", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA203": { "summary": "Acesso não permitido a partir deste endereço de IP.", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA203", "message": "Acesso não permitido a partir deste endereço de IP.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA205": { "summary": "Nenhum endereço de IP cadastrado na whitelist. Cadastre o IP de origem antes ...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA205", "message": "Nenhum endereço de IP cadastrado na whitelist. Cadastre o IP de origem antes de operar.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Transação não encontrada", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Transação não encontrada", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/withdraw' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/withdraw';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/withdraw',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/send-pix", "description": "Enviar Pix" } } }, "/withdraw/qrcode": { "post": { "summary": "Criar Saque usando QR Code", "description": "Realiza o pagamento (cash out) usando um **QR Code Pix** (estático/dinâmico). Se `amount` não for informado, o valor embutido no QR Code será utilizado. PayZu processa QR Code dinâmico e estático.", "operationId": "post_withdraw_qrcode", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostWithdrawQrcodeRequest" } } } }, "responses": { "200": { "description": "Saque criado a partir do QR Code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "with_amount": { "summary": "Criado com valor personalizado", "value": { "id": "PAYZU20261106M5KT9WB2LC000000", "status": "PENDING", "amount": 20, "type": "WITHDRAW", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "serviceFeeCharged": 1, "payerName": null, "payerDocument": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "payerAccountNumber": "000000", "withdrawPixKey": "88888888888", "withdrawPixType": "cpf", "receiverName": null, "receiverDocument": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "receiverAccountNumber": null, "endToEndId": null, "createdAt": "2025-11-06T19:08:55.848Z", "updatedAt": "2025-11-06T19:08:55.848Z", "paidAt": null, "clientReference": "order-123", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } }, "without_amount": { "summary": "Criado usando o valor do QR Code", "value": { "id": "PAYZU20261106M5KT9WB2LD000000", "status": "PENDING", "amount": 150, "type": "WITHDRAW", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "serviceFeeCharged": 1, "payerName": null, "payerDocument": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "payerAccountNumber": "000000", "withdrawPixKey": "example@payzu.com.br", "withdrawPixType": "email", "receiverName": null, "receiverDocument": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "receiverAccountNumber": null, "endToEndId": null, "createdAt": "2025-11-06T19:10:00.000Z", "updatedAt": "2025-11-06T19:10:00.000Z", "paidAt": null, "clientReference": "order-12323456", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "QR Code inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "QR Code inválido ou mal formatado", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "QR Code inválido ou mal formatado", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZS603": { "summary": "O valor informado (R$ 100,00) não corresponde ao valor do QR Code (R$ 150,00).", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZS603", "message": "O valor informado (R$ 100,00) não corresponde ao valor do QR Code (R$ 150,00).", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZS604": { "summary": "É obrigatório informar o valor.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZS604", "message": "É obrigatório informar o valor.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZS600": { "summary": "O valor mínimo do saque é R$ 1,00.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZS600", "message": "O valor mínimo do saque é R$ 1,00.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZS601": { "summary": "O valor máximo do saque é R$ 50.000,00.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZS601", "message": "O valor máximo do saque é R$ 50.000,00.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZS602": { "summary": "O valor do saque está fora dos limites da instituição financeira.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZS602", "message": "O valor do saque está fora dos limites da instituição financeira.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZK601": { "summary": "QR Code inválido ou mal formatado.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZK601", "message": "QR Code inválido ou mal formatado.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA200": { "summary": "Forbidden", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA200", "message": "Forbidden", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA203": { "summary": "Acesso não permitido a partir deste endereço de IP.", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA203", "message": "Acesso não permitido a partir deste endereço de IP.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA205": { "summary": "Nenhum endereço de IP cadastrado na whitelist. Cadastre o IP de origem antes ...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA205", "message": "Nenhum endereço de IP cadastrado na whitelist. Cadastre o IP de origem antes de operar.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Operação recusada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZS200": { "summary": "Saque não permitido para esta conta no momento.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZS200", "message": "Saque não permitido para esta conta no momento.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "424": { "description": "Falha na instituição financeira", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZS500": { "summary": "Nenhuma instituição financeira disponível para o saque no momento. Tente nova...", "value": { "status": "ERROR", "error": "Failed Dependency", "errorCode": "PZS500", "message": "Nenhuma instituição financeira disponível para o saque no momento. Tente novamente em instantes.", "statusCode": 424, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "retryAfterSeconds": 5 } }, "PZK101": { "summary": "Não foi possível consultar o QR Code junto à instituição financeira.", "value": { "status": "ERROR", "error": "Failed Dependency", "errorCode": "PZK101", "message": "Não foi possível consultar o QR Code junto à instituição financeira.", "statusCode": 424, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "429": { "description": "Limite de requisições excedido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG429": { "summary": "Limite de consultas atingido. Tente novamente em breve. Tente novamente em 30s.", "value": { "status": "ERROR", "error": "Too Many Requests", "errorCode": "PZG429", "message": "Limite de consultas atingido. Tente novamente em breve. Tente novamente em 30s.", "statusCode": 429, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "retryAfterSeconds": 30 } } } } } } }, "parameters": [], "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/withdraw/qrcode' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"qrCode\": \"00020101021226770014br.gov.bcb.pix2555api.payzu/pix/qr/v2/013318d6-2d7d-479e-8bb3-b5c7b9da688c5204000053039865802BR5916PAYZU 6007SAOPAULO6217051320260118278956304EC55\",\n \"amount\": 20,\n \"callbackUrl\": \"https://webhook.cool/\",\n \"description\": \"Pagamento via QR Code\",\n \"clientReference\": \"order-123\",\n \"virtualAccount\": \"loja-centro-01\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/withdraw/qrcode';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n qrCode: '00020101021226770014br.gov.bcb.pix2555api.payzu/pix/qr/v2/013318d6-2d7d-479e-8bb3-b5c7b9da688c5204000053039865802BR5916PAYZU 6007SAOPAULO6217051320260118278956304EC55',\n amount: 20,\n callbackUrl: 'https://webhook.cool/',\n description: 'Pagamento via QR Code',\n clientReference: 'order-123',\n virtualAccount: 'loja-centro-01'\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/withdraw/qrcode',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'qrCode': '00020101021226770014br.gov.bcb.pix2555api.payzu/pix/qr/v2/013318d6-2d7d-479e-8bb3-b5c7b9da688c5204000053039865802BR5916PAYZU 6007SAOPAULO6217051320260118278956304EC55',\n 'amount': 20,\n 'callbackUrl': 'https://webhook.cool/',\n 'description': 'Pagamento via QR Code',\n 'clientReference': 'order-123',\n 'virtualAccount': 'loja-centro-01'\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/send-pix", "description": "Enviar Pix" } } }, "/withdraw/proof/{id}": { "get": { "summary": "Obter comprovante de saque", "description": "Retorna o comprovante da transação como JSON com o campo `base64` (PDF codificado). Decodifique para exibir ou salvar como `.pdf`.", "operationId": "get_withdraw_proof", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "ID da transação.", "schema": { "type": "string" }, "example": "PAYZU20260817B3PL8SG5WQ000000" }, { "in": "query", "name": "type", "required": false, "description": "Formato de retorno.", "schema": { "type": "string", "enum": [ "pdf", "base64" ], "default": "pdf" }, "example": "pdf" } ], "responses": { "200": { "description": "Comprovante em PDF ou base64", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofResponse" }, "examples": { "base64": { "summary": "Como Base64", "value": { "base64": "JVBERi0xLjQKJ..." } } } }, "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "PDF binário (formato padrão, quando `type=pdf`)." } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "type", "message": "Invalid option: expected one of \"base64\"|\"pdf\"" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Transação não encontrada", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Transação não encontrada", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Operação recusada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZC320": { "summary": "Transação ainda não processada.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZC320", "message": "Transação ainda não processada.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZC321": { "summary": "Comprovante indisponível: transação cancelada sem documento.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZC321", "message": "Comprovante indisponível: transação cancelada sem documento.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZI103": { "summary": "Dado interno ausente para concluir a operação.", "value": { "status": "ERROR", "error": "Internal Server Error", "errorCode": "PZI103", "message": "Dado interno ausente para concluir a operação.", "statusCode": 500, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/withdraw/proof/PAYZU20260817B3PL8SG5WQ000000' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/withdraw/proof/PAYZU20260817B3PL8SG5WQ000000';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/withdraw/proof/PAYZU20260817B3PL8SG5WQ000000',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/send-pix", "description": "Enviar Pix" } } }, "/user": { "get": { "summary": "Informações da conta", "description": "Perfil da conta, permissões, limites e regras de tarifas.", "operationId": "get_user", "tags": [ "Account" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Dados da conta", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountNumber": { "type": [ "string", "null" ], "description": "Identificador público da conta." }, "branch": { "type": "string", "pattern": "^[0-9]{4}$", "description": "Agência da conta.", "example": "0001" }, "name": { "type": "string", "description": "Nome cadastrado da conta." }, "role": { "type": "string", "description": "Perfil da conta.", "enum": [ "USER" ] }, "balanceAvailable": { "type": "number", "description": "Saldo livre para saques e transferências, em reais." }, "balanceBlocked": { "type": "number", "description": "Parte do saldo retida, em reais." }, "status": { "type": "string", "description": "Situação da conta.", "enum": [ "ACTIVE" ] }, "allowWithdraw": { "type": "boolean", "description": "Quando falso, a criação de saques é recusada por falta de permissão (PZS200)." }, "allowDeposit": { "type": "boolean", "description": "Quando falso, a criação de cobranças Pix de entrada é recusada por falta de permissão (PZD200)." }, "cashInTicketMin": { "type": "number", "description": "Valor mínimo aceito em cada cobrança de entrada, em reais; abaixo do piso a criação é recusada." }, "cashInTicketMax": { "type": "number", "description": "Valor máximo aceito em cada cobrança de entrada, em reais; acima do teto a criação é recusada." }, "cashOutTicketMin": { "type": "number", "description": "Valor mínimo por saque ou transferência interna, em reais; abaixo do piso o pedido é recusado." }, "cashOutTicketMax": { "type": "number", "description": "Valor máximo por saque ou transferência interna, em reais; acima do teto o pedido é recusado." }, "ServiceFee": { "type": [ "object", "null" ], "properties": { "cashInMinimum": { "type": "number", "description": "Piso da tarifa de entrada, em reais." }, "cashInFixed": { "type": "number", "description": "Parcela fixa da tarifa de entrada, em reais." }, "cashInPercent": { "type": "number", "description": "Percentual da tarifa de entrada." }, "cashOutMinimum": { "type": "number", "description": "Piso da tarifa de saque, em reais." }, "cashOutFixed": { "type": "number", "description": "Parcela fixa da tarifa de saque, em reais." }, "cashOutPercent": { "type": "number", "description": "Percentual da tarifa de saque." } }, "description": "Tarifas de entrada e saída da conta, em reais." }, "DailyWithdrawLimit": { "type": [ "object", "null" ], "properties": { "limit": { "type": "number", "description": "Teto diário de saída, em reais, somando saques e transferências internas." }, "used": { "type": "number", "description": "Total consumido do teto no dia, em reais, por saques e transferências internas." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data e hora da última alteração do limite diário." }, "lastReset": { "type": [ "string", "null" ], "format": "date-time", "description": "Momento da última zeragem do consumo diário." } }, "description": "Controle do teto diário de saída." } } }, "examples": { "ok": { "summary": "Informações da conta", "value": { "accountNumber": "000000", "branch": "0001", "name": "PAYZU", "role": "USER", "balanceAvailable": 231.46, "balanceBlocked": 0, "status": "ACTIVE", "allowWithdraw": true, "allowDeposit": true, "cashInTicketMin": 1, "cashInTicketMax": 5000, "cashOutTicketMin": 1, "cashOutTicketMax": 5000, "ServiceFee": { "cashInMinimum": 0, "cashInFixed": 0, "cashInPercent": 0, "cashOutMinimum": 0, "cashOutFixed": 0, "cashOutPercent": 0 }, "DailyWithdrawLimit": { "limit": 50000, "used": 1200, "updatedAt": "2025-10-21T21:16:47.759Z", "lastReset": "2025-10-21T21:16:47.759Z" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/user/balance": { "get": { "summary": "Saldo da conta", "description": "Saldos disponíveis e bloqueados.", "operationId": "get_user_balance", "tags": [ "Account" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Saldos", "content": { "application/json": { "schema": { "type": "object", "properties": { "balanceAvailable": { "type": "number", "description": "Saldo livre para saques e transferências, em reais, da conta dona do token." }, "balanceBlocked": { "type": "number", "description": "Saldo retido e indisponível, em reais." } } }, "examples": { "ok": { "summary": "Saldo atual", "value": { "balanceAvailable": 231.46, "balanceBlocked": 0 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/balance' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/balance';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/balance',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/user/transactions": { "get": { "summary": "Listar transações", "description": "Lista paginada das transações da conta com filtros.", "operationId": "get_user_transactions", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "dateFrom", "required": false, "description": "Data inicial (YYYY-MM-DD).", "schema": { "type": "string" }, "example": "2026-08-01" }, { "in": "query", "name": "dateTo", "required": false, "description": "Data final (YYYY-MM-DD).", "schema": { "type": "string" }, "example": "2026-08-31" }, { "in": "query", "name": "limit", "required": false, "description": "Itens por página.", "schema": { "type": "number", "default": 10, "minimum": 1, "maximum": 1000 }, "example": 10 }, { "in": "query", "name": "page", "required": false, "description": "Número da página.", "schema": { "type": "number", "default": 1, "minimum": 1 }, "example": 1 }, { "in": "query", "name": "id", "required": false, "description": "ID da transação.", "schema": { "type": "string" }, "example": "PAYZU20260814T6NX1CV9MK000000" }, { "in": "query", "name": "status", "required": false, "description": "Status da transação, vários separados por vírgula.\n\n`PENDING` `COMPLETED` `CANCELED` `WAITING_FOR_REFUND` `REFUNDED` `EXPIRED` `ERROR`", "schema": { "type": "string", "example": "COMPLETED,PENDING" }, "example": "COMPLETED" }, { "in": "query", "name": "type", "required": false, "description": "Tipo da transação, vários separados por vírgula.\n\n`DEPOSIT` `WITHDRAW` `COMMISSION`", "schema": { "type": "string", "example": "DEPOSIT,WITHDRAW" }, "example": "DEPOSIT" }, { "in": "query", "name": "method", "required": false, "description": "Trilho da transação, vários separados por vírgula. `PIX` `` `INTERNAL_TRANSFER`", "schema": { "type": "string", "example": "PIX,INTERNAL_TRANSFER" }, "example": "PIX" }, { "in": "query", "name": "amount", "required": false, "description": "Filtro por valor. Mínimo 0.01.", "schema": { "type": "number", "minimum": 0.01 }, "example": 15000 }, { "in": "query", "name": "document", "required": false, "description": "CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números sem formatação.", "schema": { "type": "string", "pattern": "^[0-9]{11,14}$" }, "example": "12345678901" }, { "in": "query", "name": "name", "required": false, "description": "Filtro por nome.", "schema": { "type": "string" }, "example": "Alice" }, { "in": "query", "name": "endToEndId", "required": false, "description": "ID end-to-end do Pix.", "schema": { "type": "string" }, "example": "E00000000202508172159kZ8dQ2mNb1x" }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "createdAt", "updatedAt" ], "default": "createdAt" }, "description": "Campo pelo qual ordenar" }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Direção da ordenação" }, { "name": "clientReference", "in": "query", "schema": { "type": "string", "maxLength": 64 }, "description": "Filtra por referência externa", "example": "order_12345" }, { "name": "virtualAccount", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "Subconta usada na criação.", "example": "loja-centro-01" } ], "responses": { "200": { "description": "Página de transações", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32", "description": "Quantidade de transações que atendem aos filtros da consulta." }, "pages": { "type": "integer", "format": "int32", "description": "Número de páginas para o limit informado, calculado a partir de total arredondado para cima." }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" }, "description": "Itens da página pedida, ordenados por sortBy e sortDirection." } } }, "examples": { "two": { "summary": "Dois depósitos", "value": { "total": 104, "pages": 2, "transactions": [ { "id": "PAYZU20261106M5KT9WB2LC000000", "amount": 10, "status": "PENDING", "type": "DEPOSIT", "qrCodeText": "00020126860014br.gov.bcb.pix2564qrcode.payzu.com.br/pix/66666666-7777-8888-9999-0000000000005204000053039865802BR5908PAYZPLUS6009SAO PAULO62070503***63048227", "qrCodeBase64": null, "qrCodeUrl": "https://pix.payzu.com.br/v1/pix/qr-code/PAYZU20261106M5KT9WB2LC000000", "serviceFeeCharged": 0.075, "payerDocument": null, "payerName": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "receiverDocument": null, "receiverName": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "generatedDocument": "00000000191", "generatedName": "JOAO DA SILVA", "generatedEmail": null, "endToEndId": null, "withdrawPixKey": null, "withdrawPixType": null, "paidAt": null, "createdAt": "2025-11-06T22:06:19.598Z", "updatedAt": "2025-11-06T22:06:19.598Z", "clientReference": "order_12345", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null }, { "id": "PAYZU20261106M5KT9WB2LD000000", "amount": 5.5, "status": "ERROR", "type": "WITHDRAW", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "serviceFeeCharged": 1, "payerDocument": null, "payerName": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "receiverDocument": null, "receiverName": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "generatedDocument": null, "generatedName": null, "generatedEmail": null, "endToEndId": null, "withdrawPixKey": "88888888888", "withdrawPixType": "cpf", "paidAt": null, "createdAt": "2025-11-06T19:08:55.848Z", "updatedAt": "2025-11-06T19:09:13.602Z", "clientReference": null, "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": "PIX_KEY_NOT_FOUND" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "status", "message": "Status inválido, Status válidos: PENDING, COMPLETED, CANCELED, WAITING_FOR_REFUND, REFUNDED, EXPIRED, ERROR" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/transactions' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/transactions';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/transactions',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/reconciliation", "description": "Conciliação" } } }, "/user/callbacks": { "get": { "summary": "Listar Callbacks", "description": "Retorna uma lista paginada de logs de callback (webhook) das transações do usuário.", "operationId": "get_user_callbacks", "tags": [ "Callbacks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Número da página." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Itens por página." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "createdAt", "status" ], "default": "createdAt" }, "description": "Campo de ordenação." }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Direção da ordenação." }, { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Filtra por ID de callback", "example": "cm3w7l9v20001q8f2u6c1y4be" }, { "name": "url", "in": "query", "schema": { "type": "string" }, "description": "Filtra por callback URL", "example": "https://webhook.cool/" }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "Status HTTP devolvido pelo seu endpoint.", "example": 200 }, { "name": "transactionId", "in": "query", "schema": { "type": "string" }, "example": "PAYZU20260814T6NX1CV9MK000000", "description": "ID da transação." }, { "name": "hasError", "in": "query", "schema": { "type": "boolean" }, "description": "Filtra callbacks que apresentaram erro", "example": true }, { "name": "createdAtFrom", "in": "query", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-01", "description": "Data de criação inicial." }, { "name": "createdAtTo", "in": "query", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-31", "description": "Data de criação final." } ], "responses": { "200": { "description": "Lista de callbacks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackListResponse" }, "examples": { "list": { "summary": "Página de logs de callback", "value": { "pagination": { "page": 1, "limit": 10, "hasNextPage": true }, "callbacks": [ { "id": "cmh211yjm03ohs601kf7672du", "url": "https://great-lock-79.webhook.cool", "status": 200, "transactionId": "PAYZU20261022F7HD2NQ4XR000000", "createdAt": "2025-10-22T13:26:53.219Z", "responseTime": 124, "body": { "id": "PAYZU20261022F7HD2NQ4XR000000", "type": "DEPOSIT", "status": "REFUNDED" }, "responseBody": "OK", "responseHeaders": { "content-type": "text/plain; charset=UTF-8" } } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "limit", "message": "Too big: expected number to be <=100" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/callbacks' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/callbacks';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/callbacks',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/webhooks", "description": "Webhooks" } } }, "/user/callbacks/{id}": { "get": { "summary": "Obter Callback", "description": "Retorna os detalhes de um log de callback específico.", "operationId": "get_user_callback_by_id", "tags": [ "Callbacks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "ID único do callback", "example": "cm3w7l9v20001q8f2u6c1y4be" } ], "responses": { "200": { "description": "Detalhes do callback", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackDetail" }, "examples": { "detail": { "summary": "Log de um único callback", "value": { "id": "cmh211yjm03ohs601kf7672du", "url": "https://great-lock-79.webhook.cool", "status": 200, "transactionId": "PAYZU20261022F7HD2NQ4XR000000", "createdAt": "2025-10-22T13:26:53.219Z", "responseTime": 124, "body": { "id": "PAYZU20261022F7HD2NQ4XR000000", "type": "DEPOSIT", "status": "REFUNDED" }, "responseBody": "OK", "responseHeaders": { "content-type": "text/plain; charset=UTF-8" } } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Callback não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Log de callback não encontrado", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Log de callback não encontrado", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/callbacks/cm3w7l9v20001q8f2u6c1y4be' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/callbacks/cm3w7l9v20001q8f2u6c1y4be';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/callbacks/cm3w7l9v20001q8f2u6c1y4be',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/webhooks", "description": "Webhooks" } } }, "/user/infractions": { "get": { "summary": "Listar infrações", "description": "Lista todas as infrações do usuário autenticado com paginação e filtros.", "operationId": "get_infractions", "tags": [ "Infractions" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Número da página." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Itens por página." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Status da infração, vários separados por vírgula.\n\n`OPEN` `ACKNOWLEDGED` `DEFENDED` `ANSWERED` `WAITING_PSP` `WAITING_ADJUSTMENTS` `CLOSED` `CANCELLED`", "example": "OPEN" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Tipo da infração, vários separados por vírgula.\n\n`REFUND_REQUEST` `FRAUD` `REFUND_CANCELLED`", "example": "REFUND_REQUEST" }, { "name": "endToEndId", "in": "query", "schema": { "type": "string" }, "example": "E00000000202508172159kZ8dQ2mNb1x", "description": "ID end-to-end do Pix." }, { "name": "transactionId", "in": "query", "schema": { "type": "string" }, "example": "PAYZU20260814T6NX1CV9MK000000", "description": "ID da transação." }, { "name": "amountMin", "in": "query", "schema": { "type": "number" }, "example": 10.9, "description": "Valor mínimo." }, { "name": "amountMax", "in": "query", "schema": { "type": "number" }, "example": 500, "description": "Valor máximo." }, { "name": "analysisResult", "in": "query", "schema": { "type": "string" }, "description": "Resultado da análise, vários separados por vírgula.\n\n`AGREED` `DISAGREED`", "example": "AGREED" }, { "name": "reportedBy", "in": "query", "schema": { "type": "string" }, "description": "Quem abriu a infração, vários separados por vírgula.\n\n`DEBITED_PARTICIPANT` `CREDITED_PARTICIPANT`", "example": "DEBITED_PARTICIPANT" }, { "name": "participantDocument", "in": "query", "schema": { "type": "string" }, "example": "12345678901", "description": "CPF ou CNPJ do participante." }, { "name": "participantName", "in": "query", "schema": { "type": "string" }, "example": "John Doe", "description": "Nome do participante." }, { "name": "sortBy", "in": "query", "required": false, "description": "Campo de ordenação.", "schema": { "type": "string", "enum": [ "createdAt", "updatedAt" ], "default": "createdAt" } }, { "name": "sortDirection", "in": "query", "required": false, "description": "Direção da ordenação.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "reportedAtFrom", "in": "query", "required": false, "description": "Filtro: reportedAt a partir de.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-01" }, { "name": "reportedAtTo", "in": "query", "required": false, "description": "Filtro: reportedAt até.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-31" }, { "name": "createdAtFrom", "in": "query", "required": false, "description": "Filtro: createdAt a partir de.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-01" }, { "name": "createdAtTo", "in": "query", "required": false, "description": "Filtro: createdAt até.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-31" }, { "name": "expiresAtFrom", "in": "query", "required": false, "description": "Filtro: expiresAt a partir de.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-01" }, { "name": "expiresAtTo", "in": "query", "required": false, "description": "Filtro: expiresAt até.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-31" }, { "name": "updatedAtFrom", "in": "query", "required": false, "description": "Filtro: updatedAt a partir de.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-01" }, { "name": "updatedAtTo", "in": "query", "required": false, "description": "Filtro: updatedAt até.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-31" }, { "name": "id", "in": "query", "required": false, "description": "Filtro por ID da infração.", "schema": { "type": "string" }, "example": "cm3w7n2p60002q8f2h7d3z5cf" }, { "name": "protocol", "in": "query", "required": false, "description": "Filtro por protocolo.", "schema": { "type": "string" }, "example": "2f8b1c4a-9d33-4e57-b0aa-7c6d5e4f3210" } ], "responses": { "200": { "description": "Lista de infrações com paginação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfractionListResponse" }, "examples": { "success": { "summary": "Lista com as infrações", "value": { "infractions": [ { "id": "infraction_id", "protocol": "PROTOCOL123", "status": "OPEN", "type": "FRAUD", "reportedBy": "DEBITED_PARTICIPANT", "reportDetails": "Transação não autorizada", "analysisResult": null, "analysisDetails": null, "reportedAt": "2024-01-15T10:30:00Z", "expiresAt": "2024-02-15T10:30:00Z", "transaction": { "id": "transaction_id", "amount": 100.5, "payerName": "João Silva", "payerDocument": "12345678901", "receiverName": "Maria Santos", "receiverDocument": "12345678901", "endToEndId": "E123456782024011510300012a4b6c8d" }, "defenseHistory": [] } ], "pagination": { "page": 1, "limit": 20, "totalItems": 45, "totalPages": 3 } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "limit", "message": "Too big: expected number to be <=100" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/infractions' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/infractions';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/infractions',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/infractions", "description": "Infrações (MED)" } } }, "/user/infractions/{id}": { "get": { "summary": "Obter Infração", "description": "Obtém uma infração específica por ID.", "operationId": "get_infractions_by_id", "tags": [ "Infractions" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "ID da infração", "example": "cm3w7n2p60002q8f2h7d3z5cf" } ], "responses": { "200": { "description": "Detalhes da infração", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfractionDetail" }, "examples": { "success": { "summary": "Detalhes da infração", "value": { "id": "infraction_123", "protocol": "PROTOCOL123", "status": "OPEN", "type": "FRAUD", "reportedBy": "DEBITED_PARTICIPANT", "reportDetails": "Transação não autorizada", "analysisResult": null, "analysisDetails": null, "reportedAt": "2024-01-15T10:30:00Z", "expiresAt": "2024-02-15T10:30:00Z", "transaction": { "id": "transaction_id", "amount": 100.5, "payerName": "João Silva", "payerDocument": "12345678901", "receiverName": "Maria Santos", "receiverDocument": "12345678901", "endToEndId": "E123456782024011510300012a4b6c8d" }, "defenseHistory": [] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Infração não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Infração não encontrada", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Infração não encontrada", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/infractions/cm3w7n2p60002q8f2h7d3z5cf' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/infractions/cm3w7n2p60002q8f2h7d3z5cf';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/infractions/cm3w7n2p60002q8f2h7d3z5cf',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/infractions", "description": "Infrações (MED)" } } }, "/user/infractions/{id}/defenses": { "post": { "summary": "Criar Defesa", "description": "Cria uma defesa para uma infração específica.", "operationId": "post_infractions_defense", "tags": [ "Infractions" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "ID da infração", "example": "cm3w7n2p60002q8f2h7d3z5cf" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PostInfractionsDefenseRequest" } } } }, "responses": { "201": { "description": "Defesa criada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Defense" }, "examples": { "success": { "summary": "Defesa criada com sucesso", "value": { "id": "defense_id", "defense": "Esta transação foi devidamente autorizada pelo cliente através do app mobile.", "status": "PENDING", "infractionId": "infraction_123", "createdAt": "2024-01-16T14:20:00Z", "updatedAt": "2024-01-16T14:20:00Z", "files": [ { "name": "evidencia1.pdf", "mimeType": "application/pdf", "size": 245760, "url": "https://storage.googleapis.com/bucket/signed-url-1" } ] } } } } } }, "400": { "description": "Arquivo inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "defense", "message": "A defesa é obrigatória" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Infração não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Infração não encontrada", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Infração não encontrada", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Infração não aberta para defesa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG422": { "summary": "Não é possível defender esta infração", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZG422", "message": "Não é possível defender esta infração", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/user/infractions/cm3w7n2p60002q8f2h7d3z5cf/defenses' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN' \\\n --form 'defense=A cobranca foi autorizada pelo titular. Comprovante em anexo.' \\\n --form 'files=@evidencia.pdf'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/infractions/cm3w7n2p60002q8f2h7d3z5cf/defenses';\n\nconst form = new FormData();\nform.append('defense', 'A cobranca foi autorizada pelo titular. Comprovante em anexo.');\nform.append('files', new Blob([/* conteudo do arquivo */]), 'evidencia.pdf');\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n body: form,\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/user/infractions/cm3w7n2p60002q8f2h7d3z5cf/defenses',\n headers={'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}'},\n data={'defense': 'A cobranca foi autorizada pelo titular. Comprovante em anexo.'},\n files={'files': open('evidencia.pdf', 'rb')},\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/infractions", "description": "Infrações (MED)" } }, "get": { "summary": "Listar Defesas", "description": "Lista todas as defesas de uma infração específica.", "operationId": "get_infractions_defenses", "tags": [ "Infractions" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "ID da infração", "example": "cm3w7n2p60002q8f2h7d3z5cf" } ], "responses": { "200": { "description": "Lista de defesas", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Defense" } }, "examples": { "success": { "summary": "Lista de defesas", "value": [ { "id": "defense_id_1", "defense": "Primeira defesa enviada", "status": "DEFENDED", "infractionId": "infraction_123", "createdAt": "2024-01-16T14:20:00Z", "updatedAt": "2024-01-17T09:15:00Z", "files": [] } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/infractions/cm3w7n2p60002q8f2h7d3z5cf/defenses' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/infractions/cm3w7n2p60002q8f2h7d3z5cf/defenses';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/infractions/cm3w7n2p60002q8f2h7d3z5cf/defenses',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/infractions", "description": "Infrações (MED)" } } }, "/user/infractions/{infractionId}/defenses/{defenseId}": { "get": { "summary": "Obter Defesa", "description": "Obtém uma defesa específica de uma infração.", "operationId": "get_infractions_defense_by_id", "tags": [ "Infractions" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "infractionId", "required": true, "schema": { "type": "string" }, "description": "ID da infração", "example": "cm3w7n2p60002q8f2h7d3z5cf" }, { "in": "path", "name": "defenseId", "required": true, "schema": { "type": "string" }, "description": "ID da defesa", "example": "cm3w7p5r90003q8f2j8e4a6dg" } ], "responses": { "200": { "description": "Detalhes da defesa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Defense" }, "examples": { "success": { "summary": "Detalhes da defesa", "value": { "id": "defense_id", "defense": "Esta transação foi devidamente autorizada.", "status": "DEFENDED", "infractionId": "infraction_123", "createdAt": "2024-01-16T14:20:00Z", "updatedAt": "2024-01-17T09:15:00Z", "files": [ { "name": "evidencia1.pdf", "size": 245760, "mimeType": "application/pdf", "url": "https://storage.googleapis.com/bucket/signed-url-1" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Defesa não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Defesa não encontrada para a infração", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Defesa não encontrada para a infração", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/infractions/cm3w7n2p60002q8f2h7d3z5cf/defenses/cm3w7p5r90003q8f2j8e4a6dg' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/infractions/cm3w7n2p60002q8f2h7d3z5cf/defenses/cm3w7p5r90003q8f2j8e4a6dg';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/infractions/cm3w7n2p60002q8f2h7d3z5cf/defenses/cm3w7p5r90003q8f2j8e4a6dg',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/infractions", "description": "Infrações (MED)" } } }, "/internal-transfer": { "post": { "summary": "Criar transferência interna", "description": "Envia fundos para outra conta PayZu usando seu accountNumber de 6 dígitos. Liquida instantaneamente dentro da PayZu.", "operationId": "post_internal_transfer", "tags": [ "Internal Transfer" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostInternalTransferRequest" } } } }, "responses": { "200": { "description": "Transferência concluída", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "completed": { "summary": "Transferência concluída (lado do débito, visão do pagador)", "value": { "id": "PAYZU20260506Q8ZR3VN6HT000000", "status": "COMPLETED", "amount": 100.5, "type": "WITHDRAW", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "serviceFeeCharged": 0, "payerName": "Joao Silva", "payerDocument": "12345678901", "payerInstitutionIspb": "23066240", "payerInstitutionName": "PAYZU IP LTDA.", "payerAccountNumber": "000000", "withdrawPixKey": null, "withdrawPixType": null, "receiverName": "Maria Santos", "receiverDocument": "98765432109", "receiverInstitutionIspb": "23066240", "receiverInstitutionName": "PAYZU IP LTDA.", "receiverAccountNumber": "987654", "endToEndId": null, "clientReference": "transfer_abc_123", "createdAt": "2026-05-06T14:25:00.000Z", "updatedAt": "2026-05-06T14:25:00.123Z", "paidAt": "2026-05-06T14:25:00.123Z", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "Payload inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "receiverAccountNumber", "message": "O número da conta destinatária deve ter 6 dígitos" } ] } }, "PZC600": { "summary": "Não é permitido transferir para a própria conta.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZC600", "message": "Não é permitido transferir para a própria conta.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZC602": { "summary": "O valor mínimo da transferência é R$ 0,01.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZC602", "message": "O valor mínimo da transferência é R$ 0,01.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZC603": { "summary": "O valor máximo da transferência é R$ 50.000,00.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZC603", "message": "O valor máximo da transferência é R$ 50.000,00.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Sem permissão para transferir", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZC401": { "summary": "Transferência interna não habilitada para esta conta.", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZC401", "message": "Transferência interna não habilitada para esta conta.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZC400": { "summary": "A conta pagadora não pertence ao solicitante.", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZC400", "message": "A conta pagadora não pertence ao solicitante.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA200": { "summary": "Forbidden", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA200", "message": "Forbidden", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA203": { "summary": "Acesso não permitido a partir deste endereço de IP.", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA203", "message": "Acesso não permitido a partir deste endereço de IP.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA205": { "summary": "Nenhum endereço de IP cadastrado na whitelist. Cadastre o IP de origem antes ...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA205", "message": "Nenhum endereço de IP cadastrado na whitelist. Cadastre o IP de origem antes de operar.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Conta do recebedor não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZC300": { "summary": "Conta destinatária inválida ou não encontrada.", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZC300", "message": "Conta destinatária inválida ou não encontrada.", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "409": { "description": "Conflito com o estado atual do recurso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZC210": { "summary": "Já existe uma operação com este identificador. Verifique o clientReference in...", "value": { "status": "ERROR", "error": "Conflict", "errorCode": "PZC210", "message": "Já existe uma operação com este identificador. Verifique o clientReference informado.", "statusCode": 409, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Saldo insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZC200": { "summary": "Saldo insuficiente para esta operação.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZC200", "message": "Saldo insuficiente para esta operação.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZC201": { "summary": "Conta destinatária indisponível.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZC201", "message": "Conta destinatária indisponível.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZC202": { "summary": "O valor da transferência não cobre a taxa de cash-in do recebedor.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZC202", "message": "O valor da transferência não cobre a taxa de cash-in do recebedor.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "429": { "description": "Limite de requisições excedido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG429": { "summary": "Limite de requisições atingido. Tente novamente em breve.", "value": { "status": "ERROR", "error": "Too Many Requests", "errorCode": "PZG429", "message": "Limite de requisições atingido. Tente novamente em breve.", "statusCode": 429, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "retryAfterSeconds": 60 } } } } } } }, "parameters": [], "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/internal-transfer' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"payerAccountNumber\": \"000000\",\n \"receiverAccountNumber\": \"987654\",\n \"amount\": 100.5,\n \"description\": \"Pagamento referente a fatura #1234\",\n \"callbackUrl\": \"https://webhook.cool/\",\n \"clientReference\": \"transfer_abc_123\",\n \"virtualAccount\": \"loja-centro-01\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/internal-transfer';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n payerAccountNumber: '000000',\n receiverAccountNumber: '987654',\n amount: 100.5,\n description: 'Pagamento referente a fatura #1234',\n callbackUrl: 'https://webhook.cool/',\n clientReference: 'transfer_abc_123',\n virtualAccount: 'loja-centro-01'\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/internal-transfer',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'payerAccountNumber': '000000',\n 'receiverAccountNumber': '987654',\n 'amount': 100.5,\n 'description': 'Pagamento referente a fatura #1234',\n 'callbackUrl': 'https://webhook.cool/',\n 'clientReference': 'transfer_abc_123',\n 'virtualAccount': 'loja-centro-01'\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/internal-transfer", "description": "Transferência interna" } }, "get": { "summary": "Obter transferência interna", "description": "Retorna os dados de uma transferência interna. Informe pelo menos um destes parâmetros: `id` ou `clientReference` (também aceita `virtualAccount`). Se informar mais de um, todos são aplicados como filtro (AND).", "operationId": "get_internal_transfer", "tags": [ "Internal Transfer" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "ID da transação", "example": "PAYZU20260814T6NX1CV9MK000000" }, { "name": "clientReference", "in": "query", "schema": { "type": "string", "maxLength": 64 }, "description": "Referência externa", "example": "order_12345" }, { "name": "virtualAccount", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "Subconta usada na criação.", "example": "loja-centro-01" } ], "responses": { "200": { "description": "Detalhes da transferência", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "found": { "summary": "Busca por clientReference", "value": { "id": "PAYZU20260506Q8ZR3VN6HT000000", "status": "COMPLETED", "amount": 100.5, "type": "WITHDRAW", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "serviceFeeCharged": 0, "payerName": "Joao Silva", "payerDocument": "12345678901", "payerInstitutionIspb": "23066240", "payerInstitutionName": "PAYZU IP LTDA.", "payerAccountNumber": "000000", "withdrawPixKey": null, "withdrawPixType": null, "receiverName": "Maria Santos", "receiverDocument": "98765432109", "receiverInstitutionIspb": "23066240", "receiverInstitutionName": "PAYZU IP LTDA.", "receiverAccountNumber": "987654", "endToEndId": null, "clientReference": "transfer_abc_123", "createdAt": "2026-05-06T14:25:00.000Z", "updatedAt": "2026-05-06T14:25:00.123Z", "paidAt": "2026-05-06T14:25:00.123Z", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "Informe `id` ou `clientReference`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "", "message": "É necessário fornecer 'id', 'clientReference' ou 'virtualAccount'" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA200": { "summary": "Forbidden", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA200", "message": "Forbidden", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA203": { "summary": "Acesso não permitido a partir deste endereço de IP.", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA203", "message": "Acesso não permitido a partir deste endereço de IP.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA205": { "summary": "Nenhum endereço de IP cadastrado na whitelist. Cadastre o IP de origem antes ...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA205", "message": "Nenhum endereço de IP cadastrado na whitelist. Cadastre o IP de origem antes de operar.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Transferência não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZC301": { "summary": "Transferência interna não encontrada.", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZC301", "message": "Transferência interna não encontrada.", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/internal-transfer' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/internal-transfer';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/internal-transfer',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/internal-transfer", "description": "Transferência interna" } } }, "/user/transactions/{id}": { "get": { "summary": "Listar detalhes da transação", "description": "Recupera uma única transação com seu log de callback e as infrações vinculadas.", "operationId": "get_user_transaction_by_id", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "PAYZU20260814T6NX1CV9MK000000", "description": "ID da transação." } ], "responses": { "200": { "description": "Detalhes da transação", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "Infraction": { "type": "array", "description": "Histórico completo de infrações desta transação.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador da infração ligada a esta transação." }, "status": { "type": "string", "description": "Situação atual da infração.", "enum": [ "WAITING_PSP", "CLOSED", "OPEN", "CANCELLED", "ACKNOWLEDGED", "DEFENDED", "ANSWERED", "WAITING_ADJUSTMENTS" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em que a infração foi registrada na PayZu." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data e hora da última alteração no registro da infração." } } } }, "CallbackLog": { "type": "array", "description": "Tentativas de entrega do webhook desta transação (mais recentes primeiro)", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do registro de envio; há um registro por tentativa de callback da transação." }, "url": { "type": "string", "description": "Endereço que recebeu o callback: a callbackUrl da transação ou a URL do webhook cadastrado." }, "status": { "type": "integer", "description": "Código de status HTTP retornado pelo receptor" }, "responseTime": { "type": "number", "description": "Tempo de ida e volta em ms" }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em que a tentativa de envio do callback foi registrada." } } } } } } ] } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Transação não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Transação não encontrada", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Transação não encontrada", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/transactions/PAYZU20260814T6NX1CV9MK000000' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/transactions/PAYZU20260814T6NX1CV9MK000000';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/transactions/PAYZU20260814T6NX1CV9MK000000',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/reconciliation", "description": "Conciliação" } } }, "/user/report": { "post": { "summary": "Gerar relatório de transações", "description": "Enfileira um job assíncrono que gera um relatório CSV das transações para o período e filtros informados.", "operationId": "post_user_report", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostUserReportRequest" } } } }, "responses": { "202": { "description": "Report job aceito (job enfileirado)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportJobAccepted" }, "examples": { "accepted": { "summary": "Job enfileirado", "value": { "id": "5224fd4e-0abb-4498-a79b-9398ea6712ad", "status": "PENDING", "createdAt": "2026-05-06T16:39:52.944Z", "updatedAt": "2026-05-06T16:39:52.944Z", "params": { "status": [], "type": [], "dateFrom": "2026-05-01T00:00:00.000Z", "dateTo": "2026-05-06T00:00:00.000Z" }, "writtenRows": 0, "storageExpiresAt": null } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "dateFrom", "message": "Invalid input: expected date, received undefined" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Nenhuma transação no filtro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG422": { "summary": "Nenhuma transação encontrada para o filtro aplicado.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZG422", "message": "Nenhuma transação encontrada para o filtro aplicado.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "parameters": [], "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/user/report' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"dateFrom\": \"2026-07-01T00:00:00Z\",\n \"dateTo\": \"2026-07-31T23:59:59Z\",\n \"status\": [\n \"PENDING\"\n ],\n \"type\": [\n \"DEPOSIT\"\n ]\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/report';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n dateFrom: '2026-07-01T00:00:00Z',\n dateTo: '2026-07-31T23:59:59Z',\n status: [\n 'PENDING'\n ],\n type: [\n 'DEPOSIT'\n ]\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/user/report',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'dateFrom': '2026-07-01T00:00:00Z',\n 'dateTo': '2026-07-31T23:59:59Z',\n 'status': [\n 'PENDING'\n ],\n 'type': [\n 'DEPOSIT'\n ]\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/reconciliation", "description": "Conciliação" } }, "get": { "summary": "Listar jobs de relatório", "operationId": "list_user_reports", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Número da página." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Itens por página." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "RUNNING", "COMPLETED", "FAILED" ] }, "description": "Status do relatório.\n\n`PENDING` `RUNNING` `COMPLETED` `FAILED`" }, { "name": "createdAtFrom", "in": "query", "required": false, "description": "Filtro: criado a partir de.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-01" }, { "name": "createdAtTo", "in": "query", "required": false, "description": "Filtro: criado até.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-31" }, { "name": "updatedAtFrom", "in": "query", "required": false, "description": "Filtro: atualizado a partir de.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-01" }, { "name": "updatedAtTo", "in": "query", "required": false, "description": "Filtro: atualizado até.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-31" }, { "name": "sortBy", "in": "query", "required": false, "description": "Campo de ordenação.", "schema": { "type": "string", "enum": [ "createdAt", "updatedAt" ], "default": "createdAt" } }, { "name": "sortDirection", "in": "query", "required": false, "description": "Direção da ordenação.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "Página de jobs de relatório", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Quantidade de solicitações de relatório do usuário que atendem aos filtros." }, "pages": { "type": "integer", "description": "Número de páginas para o limit informado, calculado a partir de total arredondado para cima." }, "reports": { "type": "array", "items": { "$ref": "#/components/schemas/ReportJob" }, "description": "Solicitações de relatório da página pedida, com id, status e datas." } } }, "examples": { "list": { "value": { "total": 9, "pages": 3, "reports": [ { "id": "5224fd4e-0abb-4498-a79b-9398ea6712ad", "status": "COMPLETED", "createdAt": "2026-05-06T16:39:52.944Z", "updatedAt": "2026-05-06T16:39:53.500Z", "expiresAt": "2026-05-13T16:39:52.996Z" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "limit", "message": "Too big: expected number to be <=100" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "description": "Lista os jobs de relatório criados pelo usuário autenticado.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/report' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/report';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/report',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/reconciliation", "description": "Conciliação" } } }, "/user/report/{id}": { "get": { "summary": "Consultar status do relatório", "operationId": "get_user_report", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01997c3a-8f21-7c4d-9e05-3b6a1d2f4c78", "description": "ID do relatório." } ], "responses": { "200": { "description": "Job de relatório", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportJobDetail" }, "examples": { "completed": { "value": { "id": "5224fd4e-0abb-4498-a79b-9398ea6712ad", "status": "COMPLETED", "createdAt": "2026-05-06T16:39:52.944Z", "updatedAt": "2026-05-06T16:39:53.500Z", "expiresAt": "2026-05-13T16:39:52.996Z", "params": { "status": [], "type": [], "dateFrom": "2026-05-01T00:00:00.000Z", "dateTo": "2026-05-06T00:00:00.000Z" }, "writtenRows": 1284 } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "id", "message": "Invalid UUID" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Relatório não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Relatório não encontrado.", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Relatório não encontrado.", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "description": "Retorna o status e os metadados de um job de relatório específico pelo `id`.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/report/01997c3a-8f21-7c4d-9e05-3b6a1d2f4c78' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/report/01997c3a-8f21-7c4d-9e05-3b6a1d2f4c78';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/report/01997c3a-8f21-7c4d-9e05-3b6a1d2f4c78',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/reconciliation", "description": "Conciliação" } } }, "/user/report/{id}/download": { "post": { "summary": "Baixar relatório", "description": "Retorna uma URL assinada de curta duração para baixar o arquivo CSV.", "operationId": "download_user_report", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01997c3a-8f21-7c4d-9e05-3b6a1d2f4c78", "description": "ID do relatório." } ], "responses": { "200": { "description": "URL de download assinada", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL assinada de curta duração para baixar o CSV (validade de 5 min)" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Quando a URL assinada expira" } } }, "examples": { "ok": { "value": { "url": "https://storage.googleapis.com//relatorio-transacoes-06-05-2026_06-05-2026_5224fd4e-...csv?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=300&...", "expiresAt": "2026-05-06T16:48:34.889Z" } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "id", "message": "Invalid UUID" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Relatório não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Relatório não encontrado.", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Relatório não encontrado.", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "410": { "description": "Arquivo do relatório expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG410": { "summary": "Relatório expirou e não está mais disponível para download.", "value": { "status": "ERROR", "error": "Gone", "errorCode": "PZG410", "message": "Relatório expirou e não está mais disponível para download.", "statusCode": 410, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Relatório ainda processando", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG422": { "summary": "Processamento de relatório ainda não concluido.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZG422", "message": "Processamento de relatório ainda não concluido.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/user/report/01997c3a-8f21-7c4d-9e05-3b6a1d2f4c78/download' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/report/01997c3a-8f21-7c4d-9e05-3b6a1d2f4c78/download';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/user/report/01997c3a-8f21-7c4d-9e05-3b6a1d2f4c78/download',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/reconciliation", "description": "Conciliação" } } }, "/user/callbacks/resend": { "post": { "summary": "Reenviar callbacks (em lote)", "description": "Reenvia callbacks em lote para transações que correspondem aos filtros informados.", "operationId": "resend_user_callbacks", "tags": [ "Callbacks" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendUserCallbacksRequest" }, "examples": { "by_period": { "summary": "Reenvia tudo que foi pago no último dia", "value": { "createdAtFrom": "2026-05-05T00:00:00Z", "createdAtTo": "2026-05-06T00:00:00Z" } }, "filtered": { "summary": "Apenas depósitos concluídos em uma janela de 7 dias", "value": { "createdAtFrom": "2026-04-29T00:00:00Z", "createdAtTo": "2026-05-06T00:00:00Z", "transactionTypes": [ "DEPOSIT" ], "transactionStatus": [ "COMPLETED" ] } } } } } }, "responses": { "200": { "description": "Reenvio disparado", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmação de que os callbacks foram enfileirados." }, "total": { "type": "integer", "description": "Número de callbacks disparados" } } }, "examples": { "ok": { "value": { "message": "Callbacks reenviados com sucesso", "total": 42 } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "createdAtFrom", "message": "Data inicial não pode ser superior a 30 dias atrás" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Nenhuma transação correspondente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Nenhuma transação encontrada para os critérios fornecidos", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Nenhuma transação encontrada para os critérios fornecidos", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Operação recusada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG422": { "summary": "Limite de reenvios atingido. Tente novamente em 1 minuto.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZG422", "message": "Limite de reenvios atingido. Tente novamente em 1 minuto.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "parameters": [], "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/user/callbacks/resend' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"createdAtFrom\": \"2026-08-05T00:00:00Z\",\n \"createdAtTo\": \"2026-08-11T23:59:59Z\",\n \"transactionIds\": [\n \"PAYZU20260814T6NX1CV9MK000000\"\n ],\n \"transactionTypes\": [\n \"DEPOSIT\"\n ],\n \"transactionStatus\": [\n \"PENDING\"\n ],\n \"transactionEndToEndIds\": [\n \"E12345678202608121200ABCDEFGHIJK\"\n ]\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/callbacks/resend';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n createdAtFrom: '2026-08-05T00:00:00Z',\n createdAtTo: '2026-08-11T23:59:59Z',\n transactionIds: [\n 'PAYZU20260814T6NX1CV9MK000000'\n ],\n transactionTypes: [\n 'DEPOSIT'\n ],\n transactionStatus: [\n 'PENDING'\n ],\n transactionEndToEndIds: [\n 'E12345678202608121200ABCDEFGHIJK'\n ]\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/user/callbacks/resend',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'createdAtFrom': '2026-08-05T00:00:00Z',\n 'createdAtTo': '2026-08-11T23:59:59Z',\n 'transactionIds': [\n 'PAYZU20260814T6NX1CV9MK000000'\n ],\n 'transactionTypes': [\n 'DEPOSIT'\n ],\n 'transactionStatus': [\n 'PENDING'\n ],\n 'transactionEndToEndIds': [\n 'E12345678202608121200ABCDEFGHIJK'\n ]\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/webhooks", "description": "Webhooks" } } }, "/user/callbacks/resend/{transactionId}": { "post": { "summary": "Reenviar callback (individual)", "operationId": "resend_user_callback_single", "tags": [ "Callbacks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "PAYZU20260814T6NX1CV9MK000000", "description": "ID da transação." } ], "responses": { "200": { "description": "Reenvio disparado", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Texto fixo confirmando o enfileiramento do reenvio da transação informada." } } }, "examples": { "ok": { "value": { "message": "Callback reenviado com sucesso" } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Transação sem callbackUrl", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Transação não encontrada ou não possui callback configurado", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Transação não encontrada ou não possui callback configurado", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Operação recusada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG422": { "summary": "Limite de reenvios atingido. Tente novamente em 1 minuto.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZG422", "message": "Limite de reenvios atingido. Tente novamente em 1 minuto.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "description": "Reenvia o callback de uma única transação.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/user/callbacks/resend/PAYZU20260814T6NX1CV9MK000000' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/callbacks/resend/PAYZU20260814T6NX1CV9MK000000';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/user/callbacks/resend/PAYZU20260814T6NX1CV9MK000000',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/webhooks", "description": "Webhooks" } } }, "/pix/qr-code/{transactionId}": { "get": { "summary": "Renderiza o QR Code Pix (PNG)", "description": "Renderiza o QR Code Pix de um depósito como uma imagem PNG binária", "operationId": "get_pix_qrcode", "tags": [ "Pix Operations" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "PAYZU20260814T6NX1CV9MK000000", "description": "ID da transação." } ], "responses": { "200": { "description": "Imagem do QR Code", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Transação sem QR Code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZK601": { "summary": "QR Code inválido ou mal formatado.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZK601", "message": "QR Code inválido ou mal formatado.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA200": { "summary": "Forbidden", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA200", "message": "Forbidden", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Transação não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZK301": { "summary": "QR Code não encontrado.", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZK301", "message": "QR Code não encontrado.", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/pix/qr-code/PAYZU20260814T6NX1CV9MK000000' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/pix/qr-code/PAYZU20260814T6NX1CV9MK000000';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/pix/qr-code/PAYZU20260814T6NX1CV9MK000000',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/receive-pix", "description": "Receber pagamento Pix" } } }, "/refund/{transactionId}": { "post": { "summary": "Estornar um Pix", "description": "Estorna uma cobrança Pix recebida. Informe `amount` para um estorno parcial, ou omita para estornar o valor total. O processamento é **assíncrono**: a resposta volta com `refundStatus: PENDING`; a conclusão é confirmada depois por webhook.", "operationId": "post_refund", "tags": [ "Refunds" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "transactionId", "required": true, "description": "ID da transação a estornar.", "schema": { "type": "string" }, "example": "PAYZU20260814T6NX1CV9MK000000" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" } } } }, "responses": { "200": { "description": "Estorno enfileirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "pending": { "summary": "Estorno parcial enfileirado", "value": { "id": "PAYZU20260810JD4WQ2R7ZB000000", "status": "COMPLETED", "amount": 100, "type": "DEPOSIT", "method": "PIX", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": "Fulano de Tal", "generatedDocument": "12345678901", "generatedEmail": null, "payerName": "Fulano de Tal", "payerDocument": "12345678901", "payerInstitutionIspb": "12345678", "payerInstitutionName": "Banco X", "payerAccountNumber": null, "serviceFeeCharged": 1.5, "withdrawPixKey": null, "withdrawPixType": null, "receiverName": "Loja Exemplo", "receiverDocument": "11222333000181", "receiverInstitutionIspb": "00000000", "receiverInstitutionName": "PayZu", "receiverAccountNumber": "000000", "endToEndId": "E12345678202508101200abcdef01234", "clientReference": "pedido-42", "refundEndToEndId": null, "refundAmount": 30.5, "refundStatus": "PENDING", "refundReason": "CUSTOMER_REQUEST", "refundDescription": "Devolução parcial", "refundedAt": null, "cancellationReason": null, "paidAt": "2025-08-10T12:00:00.000Z", "createdAt": "2025-08-10T11:59:00.000Z", "updatedAt": "2026-08-11T09:00:00.000Z" } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "amount", "message": "Too small: expected number to be >0" } ] } }, "PZC610": { "summary": "O valor de reembolso deve ser maior que zero.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZC610", "message": "O valor de reembolso deve ser maior que zero.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZC611": { "summary": "O valor de reembolso excede o valor disponível da transação.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZC611", "message": "O valor de reembolso excede o valor disponível da transação.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZC403": { "summary": "Reembolso não habilitado para esta conta.", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZC403", "message": "Reembolso não habilitado para esta conta.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA200": { "summary": "Forbidden", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA200", "message": "Forbidden", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA203": { "summary": "Acesso não permitido a partir deste endereço de IP.", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA203", "message": "Acesso não permitido a partir deste endereço de IP.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA205": { "summary": "Nenhum endereço de IP cadastrado na whitelist. Cadastre o IP de origem antes ...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA205", "message": "Nenhum endereço de IP cadastrado na whitelist. Cadastre o IP de origem antes de operar.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZC310": { "summary": "Transação não encontrada.", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZC310", "message": "Transação não encontrada.", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "409": { "description": "Conflito com o estado atual do recurso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZC221": { "summary": "Esta transação já foi reembolsada.", "value": { "status": "ERROR", "error": "Conflict", "errorCode": "PZC221", "message": "Esta transação já foi reembolsada.", "statusCode": 409, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZC210": { "summary": "Já existe uma operação com este identificador. Verifique o clientReference in...", "value": { "status": "ERROR", "error": "Conflict", "errorCode": "PZC210", "message": "Já existe uma operação com este identificador. Verifique o clientReference informado.", "statusCode": 409, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Estorno não permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZC220": { "summary": "Apenas depósitos ou saques podem ser reembolsados.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZC220", "message": "Apenas depósitos ou saques podem ser reembolsados.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZC223": { "summary": "Transação de liquidação de cartão não pode ser reembolsada nem alterada.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZC223", "message": "Transação de liquidação de cartão não pode ser reembolsada nem alterada.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "429": { "description": "Limite de requisições excedido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG429": { "summary": "Limite de reembolsos atingido. Tente novamente em 1 minuto.", "value": { "status": "ERROR", "error": "Too Many Requests", "errorCode": "PZG429", "message": "Limite de reembolsos atingido. Tente novamente em 1 minuto.", "statusCode": 429, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "retryAfterSeconds": 60 } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZI103": { "summary": "Dado interno ausente para concluir a operação.", "value": { "status": "ERROR", "error": "Internal Server Error", "errorCode": "PZI103", "message": "Dado interno ausente para concluir a operação.", "statusCode": 500, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/refund/PAYZU20260814T6NX1CV9MK000000' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"amount\": 30.5,\n \"description\": \"Estorno solicitado pelo cliente\",\n \"clientReference\": \"refund-2026-0001\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/refund/PAYZU20260814T6NX1CV9MK000000';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n amount: 30.5,\n description: 'Estorno solicitado pelo cliente',\n clientReference: 'refund-2026-0001'\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/refund/PAYZU20260814T6NX1CV9MK000000',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'amount': 30.5,\n 'description': 'Estorno solicitado pelo cliente',\n 'clientReference': 'refund-2026-0001'\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/med", "description": "MED" } } }, "/user/webhooks": { "post": { "summary": "Criar webhook", "description": "Cadastra um endpoint de webhook. Se `generateSecret` for true, a resposta traz o `secret` HMAC (exibido só aqui).", "operationId": "post_user_webhook", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateRequest" } } } }, "responses": { "201": { "description": "Webhook criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" }, "examples": { "created": { "value": { "id": "cm3w7k1t40000q8f2r5b9x3ad", "url": "https://sualoja.com.br/webhook", "active": true, "events": [ "TRANSACTION_COMPLETED", "TRANSACTION_REFUNDED" ], "hasSecret": true, "createdAt": "2026-08-10T12:00:00.000Z", "updatedAt": "2026-08-10T12:00:00.000Z", "secret": "whsec_9f8a2b7c6d5e4f3a2b1c0d9e8f7a6b5c" } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "url", "message": "Invalid URL" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "409": { "description": "Conflito com o estado atual do recurso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG409": { "summary": "Limite de 5 webhooks ativos atingido", "value": { "status": "ERROR", "error": "Conflict", "errorCode": "PZG409", "message": "Limite de 5 webhooks ativos atingido", "statusCode": 409, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/user/webhooks' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"url\": \"https://sualoja.com.br/webhook\",\n \"events\": [],\n \"generateSecret\": false,\n \"active\": true\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/webhooks';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n url: 'https://sualoja.com.br/webhook',\n events: [],\n generateSecret: false,\n active: true\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/user/webhooks',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'url': 'https://sualoja.com.br/webhook',\n 'events': [],\n 'generateSecret': False,\n 'active': True\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/webhooks", "description": "Webhooks" } }, "get": { "summary": "Listar webhooks", "description": "Lista os webhooks cadastrados na conta.", "operationId": "get_user_webhooks", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "active", "required": false, "description": "Filtra pelo status ativo.", "schema": { "type": "boolean" }, "example": true } ], "responses": { "200": { "description": "Lista de webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" }, "examples": { "list": { "value": { "webhooks": [ { "id": "cm3w7k1t40000q8f2r5b9x3ad", "url": "https://sualoja.com.br/webhook", "active": true, "events": [ "TRANSACTION_COMPLETED", "TRANSACTION_REFUNDED" ], "hasSecret": true, "createdAt": "2026-08-10T12:00:00.000Z", "updatedAt": "2026-08-10T12:00:00.000Z" } ] } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "active", "message": "Invalid input: expected boolean, received string" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/webhooks' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/webhooks';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/webhooks',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/webhooks", "description": "Webhooks" } } }, "/user/webhooks/{id}": { "get": { "summary": "Consultar webhook", "description": "Retorna um webhook.", "operationId": "get_user_webhook", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Id do webhook.", "schema": { "type": "string" }, "example": "cm3w7k1t40000q8f2r5b9x3ad" } ], "responses": { "200": { "description": "Webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "examples": { "webhook": { "value": { "id": "cm3w7k1t40000q8f2r5b9x3ad", "url": "https://sualoja.com.br/webhook", "active": true, "events": [ "TRANSACTION_COMPLETED", "TRANSACTION_REFUNDED" ], "hasSecret": true, "createdAt": "2026-08-10T12:00:00.000Z", "updatedAt": "2026-08-10T12:00:00.000Z" } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "id", "message": "Invalid cuid2" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Webhook não encontrado", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Webhook não encontrado", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/webhooks", "description": "Webhooks" } }, "patch": { "summary": "Atualizar webhook", "description": "Atualiza a url, o status ativo ou os eventos de um webhook. Informe pelo menos um campo.", "operationId": "patch_user_webhook", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Id do webhook.", "schema": { "type": "string" }, "example": "cm3w7k1t40000q8f2r5b9x3ad" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdateRequest" } } } }, "responses": { "200": { "description": "Webhook atualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "examples": { "webhook": { "value": { "id": "cm3w7k1t40000q8f2r5b9x3ad", "url": "https://sualoja.com.br/webhook", "active": true, "events": [ "TRANSACTION_COMPLETED", "TRANSACTION_REFUNDED" ], "hasSecret": true, "createdAt": "2026-08-10T12:00:00.000Z", "updatedAt": "2026-08-10T12:00:00.000Z" } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "", "message": "Pelo menos um campo deve ser fornecido" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Webhook não encontrado", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Webhook não encontrado", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "409": { "description": "Conflito com o estado atual do recurso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG409": { "summary": "Limite de 5 webhooks ativos atingido", "value": { "status": "ERROR", "error": "Conflict", "errorCode": "PZG409", "message": "Limite de 5 webhooks ativos atingido", "statusCode": 409, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request PATCH \\\n --url 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"url\": \"https://sualoja.com.br/webhook\",\n \"active\": true,\n \"events\": [\n \"TRANSACTION_PENDING\"\n ]\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad';\n\nconst response = await fetch(url, {\n method: 'PATCH',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n url: 'https://sualoja.com.br/webhook',\n active: true,\n events: [\n 'TRANSACTION_PENDING'\n ]\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.patch(\n 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'url': 'https://sualoja.com.br/webhook',\n 'active': True,\n 'events': [\n 'TRANSACTION_PENDING'\n ]\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/webhooks", "description": "Webhooks" } }, "delete": { "summary": "Remover webhook", "description": "Remove um webhook.", "operationId": "delete_user_webhook", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Id do webhook.", "schema": { "type": "string" }, "example": "cm3w7k1t40000q8f2r5b9x3ad" } ], "responses": { "204": { "description": "Webhook removido." }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "id", "message": "Invalid cuid2" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Webhook não encontrado", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Webhook não encontrado", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request DELETE \\\n --url 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad';\n\nconst response = await fetch(url, {\n method: 'DELETE',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.delete(\n 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/webhooks", "description": "Webhooks" } } }, "/user/webhooks/{id}/rotate-secret": { "post": { "summary": "Rotacionar segredo do webhook", "description": "Gera um novo segredo de assinatura HMAC e invalida o anterior. O novo `secret` é exibido só nesta resposta.", "operationId": "post_user_webhook_rotate_secret", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Id do webhook.", "schema": { "type": "string" }, "example": "cm3w7k1t40000q8f2r5b9x3ad" } ], "responses": { "200": { "description": "Novo segredo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateSecretResponse" }, "examples": { "rotated": { "value": { "secret": "whsec_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d" } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "id", "message": "Invalid cuid2" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Webhook não encontrado", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Webhook não encontrado", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad/rotate-secret' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad/rotate-secret';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad/rotate-secret',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/webhooks", "description": "Webhooks" } } }, "/user/webhooks/sent/quantity": { "get": { "summary": "Contar callbacks enviados", "description": "Retorna quantos callbacks foram enviados, opcionalmente filtrando por webhook.", "operationId": "get_user_webhooks_sent_quantity", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "webhookId", "required": false, "description": "Filtra a contagem por id de webhook.", "schema": { "type": "string" }, "example": "cm3w7k1t40000q8f2r5b9x3ad" } ], "responses": { "200": { "description": "Quantidade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentWebhooksQuantity" }, "examples": { "qty": { "value": { "quantity": 128 } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "webhookId", "message": "Invalid cuid2" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Webhook não encontrado", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Webhook não encontrado", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/webhooks/sent/quantity' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/webhooks/sent/quantity';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/webhooks/sent/quantity',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/webhooks", "description": "Webhooks" } } }, "/user/webhooks/{id}/sent/{callbackId}": { "get": { "summary": "Detalhe de callback enviado", "description": "Retorna o detalhe de entrega de um callback enviado.", "operationId": "get_user_webhook_sent_detail", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Id do webhook.", "schema": { "type": "string" }, "example": "cm3w7k1t40000q8f2r5b9x3ad" }, { "in": "path", "name": "callbackId", "required": true, "description": "Id do log de callback.", "schema": { "type": "string" }, "example": "cm3w7l9v20001q8f2u6c1y4be" } ], "responses": { "200": { "description": "Detalhe de entrega do callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentWebhookDetailResponse" } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "callbackId", "message": "Invalid cuid2" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Log de webhook enviado não encontrado", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Log de webhook enviado não encontrado", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad/sent/cm3w7l9v20001q8f2u6c1y4be' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad/sent/cm3w7l9v20001q8f2u6c1y4be';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/webhooks/cm3w7k1t40000q8f2r5b9x3ad/sent/cm3w7l9v20001q8f2u6c1y4be',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/webhooks", "description": "Webhooks" } } }, "/user/callbacks/resend/webhook/{webhookId}": { "post": { "summary": "Reenviar callbacks por webhook", "description": "Enfileira o reenvio em lote dos callbacks falhos de um webhook.", "operationId": "resend_user_callbacks_webhook", "tags": [ "Callbacks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "webhookId", "required": true, "description": "Id do webhook.", "schema": { "type": "string" }, "example": "cm3w7k1t40000q8f2r5b9x3ad" } ], "responses": { "200": { "description": "Callbacks aceitos para reenvio. Aceite não é entrega: o enfileiramento acontece depois da resposta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnqueuedCallback" }, "examples": { "queued": { "summary": "Callbacks enfileirados", "value": { "enqueued": { "count": 12, "truncated": false, "items": [ { "transactionId": "PAYZU20260811K7M2X9QP4T000000", "webhookId": "cm3w7k1t40000q8f2r5b9x3ad", "eventType": "TRANSACTION_COMPLETED" }, { "transactionId": "PAYZU20260812H9VB3KQ7XM000000", "webhookId": "cm3w7k1t40000q8f2r5b9x3ad", "eventType": "TRANSACTION_CANCELED" } ] } } }, "truncated": { "summary": "Mais de 500 callbacks: items vem truncado, count é o total real", "value": { "enqueued": { "count": 1873, "truncated": true, "items": [ { "transactionId": "PAYZU20260811K7M2X9QP4T000000", "webhookId": "cm3w7k1t40000q8f2r5b9x3ad", "eventType": "TRANSACTION_COMPLETED" } ] } } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "webhookId", "message": "Invalid cuid2" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA206": { "summary": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao represe...", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA206", "message": "Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Webhook não encontrado, inativo ou de outra conta (PZW300), ou nenhum callback falho para os filtros (PZW310).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZW300": { "summary": "Webhook não encontrado, inativo ou de outra conta", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZW300", "message": "Webhook não encontrado, está inativo, ou não pertence ao usuário", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZW310": { "summary": "Nenhum callback falho para este webhook", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZW310", "message": "Nenhum callback falho encontrado para o webhook", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Operação recusada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG422": { "summary": "Limite de reenvios atingido. Tente novamente em 1 minuto.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZG422", "message": "Limite de reenvios atingido. Tente novamente em 1 minuto.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/user/callbacks/resend/webhook/cm3w7k1t40000q8f2r5b9x3ad' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/callbacks/resend/webhook/cm3w7k1t40000q8f2r5b9x3ad';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/user/callbacks/resend/webhook/cm3w7k1t40000q8f2r5b9x3ad',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/webhooks", "description": "Webhooks" } } }, "/user/bank-statements": { "get": { "summary": "Listar extrato", "description": "Lista os lançamentos do extrato da conta. `createdAtFrom` e `createdAtTo` são obrigatórios.", "operationId": "get_user_bank_statements", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "createdAtFrom", "required": true, "description": "Data inicial (obrigatória).", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-01" }, { "in": "query", "name": "createdAtTo", "required": true, "description": "Data final (obrigatória).", "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-31" }, { "in": "query", "name": "id", "required": false, "schema": { "type": "string" }, "example": "cm3w7q8s10004q8f2k9f5b7eh", "description": "ID do lançamento." }, { "in": "query", "name": "operation", "required": false, "schema": { "type": "string", "enum": [ "INCREMENT", "DECREMENT" ] }, "description": "Tipo de operação.\n\n`INCREMENT` `DECREMENT`" }, { "in": "query", "name": "reason", "required": false, "schema": { "type": "string" }, "example": "Estorno", "description": "Razão do lançamento." }, { "in": "query", "name": "transactionId", "required": false, "schema": { "type": "string" }, "example": "PAYZU20260814T6NX1CV9MK000000", "description": "ID da transação." }, { "in": "query", "name": "amountFrom", "required": false, "schema": { "type": "number" }, "example": 10.9, "description": "Valor mínimo." }, { "in": "query", "name": "amountTo", "required": false, "schema": { "type": "number" }, "example": 500, "description": "Valor máximo." }, { "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Número da página." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Itens por página." }, { "in": "query", "name": "sortBy", "required": false, "schema": { "type": "string", "enum": [ "createdAt", "amount" ], "default": "createdAt" }, "description": "Campo de ordenação." }, { "in": "query", "name": "sortDirection", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Direção da ordenação." } ], "responses": { "200": { "description": "Página do extrato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementListResponse" }, "examples": { "list": { "value": { "pagination": { "page": 1, "limit": 10, "hasNextPage": true }, "bankStatements": [ { "id": "bs_1", "amount": 100, "operation": "INCREMENT", "reason": "PIX_DEPOSIT", "balanceType": "AVAILABLE", "previousBalanceAvailable": 400, "previousBalanceBlocked": 0, "newBalanceAvailable": 500, "newBalanceBlocked": 0, "transactionId": "PAYZU2025...", "infractionId": null, "createdAt": "2026-08-10T12:00:00.000Z", "updatedAt": "2026-08-10T12:00:00.000Z" } ] } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "createdAtFrom", "message": "Invalid input: expected date, received undefined" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/bank-statements?createdAtFrom=2026-08-01&createdAtTo=2026-08-31' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/bank-statements?createdAtFrom=2026-08-01&createdAtTo=2026-08-31';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/bank-statements?createdAtFrom=2026-08-01&createdAtTo=2026-08-31',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/reconciliation", "description": "Conciliação" } } }, "/user/bank-statements/{id}": { "get": { "summary": "Consultar lançamento", "description": "Retorna um lançamento do extrato.", "operationId": "get_user_bank_statement", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Id do lançamento do extrato.", "schema": { "type": "string" }, "example": "cm3w7q8s10004q8f2k9f5b7eh" } ], "responses": { "200": { "description": "Lançamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatement" } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Extrato bancário não encontrado", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Extrato bancário não encontrado", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/bank-statements/cm3w7q8s10004q8f2k9f5b7eh' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/bank-statements/cm3w7q8s10004q8f2k9f5b7eh';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/bank-statements/cm3w7q8s10004q8f2k9f5b7eh',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/reconciliation", "description": "Conciliação" } } }, "/user/deposit-pending": { "get": { "summary": "Listar depósitos pendentes", "description": "Lista os depósitos pendentes / ainda não conciliados.", "operationId": "get_user_deposit_pending", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "status", "required": false, "description": "Status do depósito, vários separados por vírgula.\n\n`PENDING` `APPROVED` `REJECTED` `EXPIRED` `COMPLETED`", "schema": { "type": "string" }, "example": "PENDING" }, { "in": "query", "name": "document", "required": false, "schema": { "type": "string" }, "example": "12345678901", "description": "CPF ou CNPJ, apenas dígitos." }, { "in": "query", "name": "name", "required": false, "schema": { "type": "string" }, "example": "John Doe", "description": "Nome do pagador ou recebedor." }, { "in": "query", "name": "endToEndId", "required": false, "schema": { "type": "string" }, "example": "E00000000202508172159kZ8dQ2mNb1x", "description": "ID end-to-end do Pix." }, { "in": "query", "name": "amountMin", "required": false, "schema": { "type": "number", "minimum": 0.01 }, "example": 10.9, "description": "Valor mínimo." }, { "in": "query", "name": "amountMax", "required": false, "schema": { "type": "number", "minimum": 0.01 }, "example": 500, "description": "Valor máximo." }, { "in": "query", "name": "createdAtFrom", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-01", "description": "Data de criação inicial." }, { "in": "query", "name": "createdAtTo", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-31", "description": "Data de criação final." }, { "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Número da página." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Itens por página." } ], "responses": { "200": { "description": "Página de pendentes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositPendingListResponse" }, "examples": { "list": { "value": { "page": 1, "limit": 20, "hasNextPage": false, "data": [ { "id": "dp_1", "status": "PENDING", "amount": 250.5, "payerDocument": "12345678901", "payerName": "Fulano", "payerAccountNumber": null, "payerInstitutionIspb": "12345678", "payerInstitutionName": "Banco X", "receiverDocument": "11222333000181", "receiverName": "Loja", "receiverAccountNumber": "000000", "receiverInstitutionIspb": "00000000", "receiverInstitutionName": "PayZu", "endToEndId": "E12345678202608101200abcdef01234", "paidAt": "2026-08-10T12:00:00.000Z", "pixKey": null, "description": null, "approvedAt": null, "rejectedAt": null, "rejectionReason": null, "transactionId": null, "createdAt": "2026-08-10T11:59:00.000Z", "updatedAt": "2026-08-10T12:00:00.000Z" } ] } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "document", "message": "Invalid string: must match pattern /^[0-9]{11,14}$/" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/deposit-pending' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/deposit-pending';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/deposit-pending',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/reconciliation", "description": "Conciliação" } } }, "/user/deposit-pending/{id}": { "get": { "summary": "Consultar depósito pendente", "description": "Retorna um depósito pendente.", "operationId": "get_user_deposit_pending_by_id", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Id do depósito pendente.", "schema": { "type": "string" }, "example": "cm3w7r1u50005q8f2m1g6c8fj" } ], "responses": { "200": { "description": "Depósito pendente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositPending" } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG404": { "summary": "Depósito pendente não encontrado", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Depósito pendente não encontrado", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/deposit-pending/cm3w7r1u50005q8f2m1g6c8fj' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/deposit-pending/cm3w7r1u50005q8f2m1g6c8fj';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/deposit-pending/cm3w7r1u50005q8f2m1g6c8fj',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/reconciliation", "description": "Conciliação" } } }, "/user/summary": { "get": { "summary": "Resumo de transações", "description": "Totais agregados de depósitos, saques e comissão num período.", "operationId": "get_user_summary", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-01", "description": "Data inicial." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-31", "description": "Data final." }, { "in": "query", "name": "groupBy", "required": false, "schema": { "type": "string", "enum": [ "day", "hour" ], "default": "day" }, "description": "Agrupamento das transações." }, { "in": "query", "name": "grouped", "required": false, "description": "Quando true, retorna uma série agrupada por data.", "schema": { "type": "boolean" }, "example": true } ], "responses": { "200": { "description": "Resumo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Summary" }, "examples": { "summary": { "value": { "totalTransactions": 42, "deposit": { "totalAmount": 1500, "totalTransactions": 20, "statuses": { "pending": { "count": 1, "amount": 100, "serviceFeeCharged": 1.5 }, "completed": { "count": 18, "amount": 1350, "serviceFeeCharged": 20 }, "canceled": { "count": 0, "amount": 0, "serviceFeeCharged": 0 }, "expired": { "count": 1, "amount": 50, "serviceFeeCharged": 0 }, "refunded": { "count": 0, "amount": 0, "serviceFeeCharged": 0 } } }, "withdraw": { "totalAmount": 800, "totalTransactions": 12, "statuses": { "pending": { "count": 0, "amount": 0 }, "completed": { "count": 12, "amount": 800 }, "canceled": { "count": 0, "amount": 0 }, "expired": { "count": 0, "amount": 0 }, "refunded": { "count": 0, "amount": 0 } } }, "commission": { "totalAmount": 30, "totalTransactions": 10, "statuses": { "pending": { "count": 0, "amount": 0 }, "completed": { "count": 10, "amount": 30 }, "canceled": { "count": 0, "amount": 0 }, "expired": { "count": 0, "amount": 0 }, "refunded": { "count": 0, "amount": 0 } } } } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "dateFrom", "message": "Invalid input: expected date, received Date" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/summary' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/summary';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/summary',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/tutoriais/reconciliation", "description": "Conciliação" } } }, "/user/dict": { "get": { "summary": "Resolver chave DICT", "description": "Resolve uma chave Pix (DICT) para os dados do titular antes de pagar. Requer o scope WITHDRAW.", "operationId": "get_user_dict", "tags": [ "Keys and DICT" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "key", "required": true, "description": "Chave Pix a consultar (CPF, CNPJ, email, telefone ou EVP).", "schema": { "type": "string", "minLength": 1, "maxLength": 77 }, "example": "john.doe@example.com" } ], "responses": { "200": { "description": "Dados do titular da chave.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DictConsultResponse" }, "examples": { "key": { "value": { "pixKey": "+5511999998888", "name": "Fulano de Tal", "document": "***.456.789-**", "personType": "PF", "accountType": "CACC", "institutionIspb": "12345678", "institutionName": "Banco X" } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZV001": { "summary": "Dados inválidos. Verifique os campos informados.", "value": { "status": "ERROR", "error": "Bad Request", "errorCode": "PZV001", "message": "Dados inválidos. Verifique os campos informados.", "statusCode": 400, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "details": [ { "field": "key", "message": "Chave PIX inválida. Formatos aceitos: CPF, CNPJ, Email, Telefone (+5511999999999) ou EVP (UUID)" } ] } } } } } }, "401": { "description": "Falha de autenticação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZA100": { "summary": "Unauthorized", "value": { "status": "ERROR", "error": "Unauthorized", "errorCode": "PZA100", "message": "Unauthorized", "statusCode": 401, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "403": { "description": "Operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZK400": { "summary": "Consulta de chave Pix não habilitada para o usuário.", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZK400", "message": "Consulta de chave Pix não habilitada para o usuário.", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } }, "PZA200": { "summary": "Forbidden", "value": { "status": "ERROR", "error": "Forbidden", "errorCode": "PZA200", "message": "Forbidden", "statusCode": 403, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZK300": { "summary": "Chave Pix não encontrada.", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZK300", "message": "Chave Pix não encontrada.", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "422": { "description": "Operação recusada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZK200": { "summary": "Chave Pix inválida.", "value": { "status": "ERROR", "error": "Unprocessable Entity", "errorCode": "PZK200", "message": "Chave Pix inválida.", "statusCode": 422, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "424": { "description": "Falha na instituição financeira", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZI110": { "summary": "Erro de comunicação com a instituição financeira.", "value": { "status": "ERROR", "error": "Failed Dependency", "errorCode": "PZI110", "message": "Erro de comunicação com a instituição financeira.", "statusCode": 424, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } }, "429": { "description": "Limite de requisições excedido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZG429": { "summary": "Limite de consultas atingido. Tente novamente em breve. Tente novamente em 30s.", "value": { "status": "ERROR", "error": "Too Many Requests", "errorCode": "PZG429", "message": "Limite de consultas atingido. Tente novamente em breve. Tente novamente em 30s.", "statusCode": 429, "requestId": "cmbz0f8qk0001js04hp3e2n0f", "retryAfterSeconds": 30 } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "PZI101": { "summary": "Operação não suportada para esta instituição financeira.", "value": { "status": "ERROR", "error": "Internal Server Error", "errorCode": "PZI101", "message": "Operação não suportada para esta instituição financeira.", "statusCode": 500, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.processamento.com/v1/user/dict?key=john.doe%40example.com' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/dict?key=john.doe%40example.com';\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.processamento.com/v1/user/dict?key=john.doe%40example.com',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ], "externalDocs": { "url": "/docs/pix-processamento/best-practices/dict", "description": "Consulta DICT" } } }, "/user/callbacks/secret": { "post": { "tags": [ "Callbacks" ], "summary": "Criar segredo de callback", "description": "Cria o segredo de callback da conta, usado para assinar as entregas feitas ao callbackUrl da transação. O segredo é devolvido uma única vez e não pode ser lido depois.", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Criar segredo de callback", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackSecretResponse" }, "examples": { "created": { "summary": "Segredo criado", "value": { "message": "Segredo de callback criado.", "secret": "Zk8Qk1Yb3nS6xPwT2cVrJ9dLmHgA4eN7uKfR0iXsBqE" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "A conta já possui segredo de callback. Use a rota de rotação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "conflict": { "summary": "A conta já possui segredo", "value": { "status": "ERROR", "error": "Conflict", "errorCode": "PZG409", "message": "Usuário já possui um secret", "statusCode": 409, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "operationId": "create_user_callback_secret", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.processamento.com/v1/user/callbacks/secret' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/callbacks/secret';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.processamento.com/v1/user/callbacks/secret',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/user/callbacks/secret/rotate": { "patch": { "tags": [ "Callbacks" ], "summary": "Rotacionar segredo de callback", "description": "Troca o segredo de callback da conta. As entregas passam a ser assinadas com o novo segredo imediatamente.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Rotacionar segredo de callback", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateCallbackSecretResponse" }, "examples": { "rotated": { "summary": "Segredo rotacionado", "value": { "secret": "Zk8Qk1Yb3nS6xPwT2cVrJ9dLmHgA4eN7uKfR0iXsBqE" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "A conta não possui segredo de callback para rotacionar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "notFound": { "summary": "Sem segredo para rotacionar", "value": { "status": "ERROR", "error": "Not Found", "errorCode": "PZG404", "message": "Callback secret não encontrado", "statusCode": 404, "requestId": "cmbz0f8qk0001js04hp3e2n0f" } } } } } } }, "operationId": "rotate_user_callback_secret", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request PATCH \\\n --url 'https://api.payzu.processamento.com/v1/user/callbacks/secret/rotate' \\\n --header 'Authorization: Bearer $PAYZU_TOKEN'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.payzu.processamento.com/v1/user/callbacks/secret/rotate';\n\nconst response = await fetch(url, {\n method: 'PATCH',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.patch(\n 'https://api.payzu.processamento.com/v1/user/callbacks/secret/rotate',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador da transação na PayZu." }, "status": { "type": "string", "description": "Status atual da transação.", "enum": [ "PENDING", "COMPLETED", "CANCELED", "WAITING_FOR_REFUND", "REFUNDED", "EXPIRED", "ERROR" ] }, "amount": { "type": "number", "description": "Valor da transação, antes da taxa." }, "type": { "type": "string", "description": "Tipo da transação.", "enum": [ "DEPOSIT", "WITHDRAW", "COMMISSION" ] }, "qrCodeText": { "type": [ "string", "null" ], "description": "Código copia e cola do Pix." }, "qrCodeBase64": { "type": [ "string", "null" ], "description": "Imagem PNG do QR Code em base64, sem o prefixo data:." }, "qrCodeUrl": { "type": [ "string", "null" ], "description": "Rota autenticada que devolve o PNG do QR Code." }, "generatedName": { "type": [ "string", "null" ], "description": "Nome usado para montar a cobrança." }, "generatedDocument": { "type": [ "string", "null" ], "description": "CPF ou CNPJ usado como devedor na cobrança." }, "generatedEmail": { "type": [ "string", "null" ], "description": "E-mail usado para montar a cobrança." }, "payerName": { "type": [ "string", "null" ], "description": "Nome do titular da conta que enviou o Pix, como informado pela instituição de origem." }, "payerDocument": { "type": [ "string", "null" ], "description": "CPF ou CNPJ de quem enviou o Pix, informado pela instituição de origem." }, "payerInstitutionIspb": { "type": [ "string", "null" ], "description": "Código ISPB da instituição de onde saiu o Pix." }, "payerInstitutionName": { "type": [ "string", "null" ], "description": "Nome da instituição de onde saiu o Pix." }, "payerAccountNumber": { "type": [ "string", "null" ], "description": "Conta PayZu do pagador." }, "serviceFeeCharged": { "type": [ "number", "null" ], "description": "Tarifa PayZu cobrada na operação, em reais. Pode ter mais de duas casas decimais — não arredonde ao conciliar." }, "withdrawPixKey": { "type": [ "string", "null" ], "description": "Chave Pix de destino do saque, já normalizada." }, "withdrawPixType": { "type": [ "string", "null" ], "description": "Tipo da chave de destino do saque, sendo evp a chave aleatória.", "enum": [ "cpf", "cnpj", "email", "phone", "evp", null ] }, "receiverName": { "type": [ "string", "null" ], "description": "Nome do titular da conta que recebe." }, "receiverDocument": { "type": [ "string", "null" ], "description": "CPF ou CNPJ de quem recebe." }, "receiverInstitutionIspb": { "type": [ "string", "null" ], "description": "Código ISPB da instituição que recebe o Pix." }, "receiverInstitutionName": { "type": [ "string", "null" ], "description": "Nome da instituição que recebe o Pix." }, "receiverAccountNumber": { "type": [ "string", "null" ], "description": "Conta PayZu do recebedor." }, "endToEndId": { "type": [ "string", "null" ], "description": "Identificador do Pix no arranjo do Bacen, usado para rastrear a liquidação e pedir devolução." }, "createdAt": { "type": "string", "description": "Data e hora do registro da transação." }, "updatedAt": { "type": "string", "description": "Data e hora da última alteração." }, "paidAt": { "type": [ "string", "null" ], "description": "Data e hora da liquidação do Pix, informada pela instituição." }, "clientReference": { "type": [ "string", "null" ], "description": "Seu identificador da transação, devolvido em consultas e callbacks." }, "refundEndToEndId": { "type": [ "string", "null" ], "description": "ID end-to-end da transação de estorno" }, "refundAmount": { "type": [ "number", "null" ], "description": "Valor estornado." }, "refundStatus": { "type": [ "string", "null" ], "description": "Status do estorno (PENDING, COMPLETED, CANCELED, WAITING_FOR_REFUND, REFUNDED, EXPIRED, ERROR)", "enum": [ "PENDING", "COMPLETED", "CANCELED", null ] }, "refundReason": { "type": [ "string", "null" ], "description": "Motivo do estorno", "enum": [ "CUSTOMER_REQUEST", "INFRACTION", null ] }, "refundDescription": { "type": [ "string", "null" ], "description": "Descrição do estorno" }, "refundedAt": { "type": [ "string", "null" ], "description": "Data e hora em que o estorno foi processado" }, "cancellationReason": { "type": [ "string", "null" ], "description": "Motivo do cancelamento (se cancelada)" }, "virtualAccount": { "type": [ "string", "null" ], "maxLength": 50, "description": "Subconta virtual informada na criação." }, "method": { "type": "string", "enum": [ "PIX", "INTERNAL_TRANSFER" ], "description": "Método/rail da transação." } }, "description": "Representação unificada de transação usada por todos os endpoints." }, "PixKeyInfo": { "type": "object", "description": "Informações sobre uma chave Pix a partir da consulta ao DICT.", "properties": { "pixKey": { "type": "string", "description": "A chave Pix que foi consultada." }, "document": { "type": "string", "description": "CPF ou CNPJ do titular (parcialmente mascarado por privacidade)." }, "name": { "type": "string", "description": "Nome do titular da chave Pix." }, "branch": { "type": "string", "description": "Número da agência bancária (mascarado)." }, "accountNumber": { "type": "string", "description": "Número da conta (mascarado)." }, "personType": { "type": "string", "description": "Tipo de pessoa.", "enum": [ "PF", "PJ" ] }, "accountType": { "type": "string", "description": "Tipo de conta devolvido pelo DICT, como CACC, SVGS, TRAN ou SLRY." }, "institutionIspb": { "type": "string", "description": "Código ISPB da instituição financeira." }, "institutionCode": { "type": "string", "description": "Código COMPE da instituição financeira." }, "institutionName": { "type": "string", "description": "Nome da instituição financeira." } } }, "QRCodeReadResponse": { "type": "object", "description": "Informações decodificadas de um QR Code Pix.", "properties": { "qrCodeType": { "type": "string", "description": "Tipo de QR Code.", "enum": [ "STATIC", "DYNAMIC" ] }, "name": { "type": [ "string", "null" ], "description": "Nome do recebedor do pagamento." }, "document": { "type": [ "string", "null" ], "description": "CPF ou CNPJ do recebedor." }, "amount": { "type": [ "number", "null" ], "description": "Valor a ser pago." }, "originalAmount": { "type": [ "number", "null" ], "description": "Valor embutido no QR Code." }, "txid": { "type": [ "string", "null" ], "description": "Identificador da transação." }, "additionalInfo": { "type": [ "string", "null" ], "description": "Informações adicionais ou descrição." }, "expiresIn": { "type": [ "number", "null" ], "description": "Segundos até o QR Code expirar (0 para QR Codes estáticos)." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Data de criação do QR Code (para QR Codes dinâmicos)." } } }, "InfractionDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador da contestação dentro da PayZu, usado nas rotas de consulta e no envio da defesa." }, "protocol": { "type": "string", "description": "Código da contestação no Bacen." }, "status": { "type": "string", "enum": [ "WAITING_PSP", "CLOSED", "OPEN", "CANCELLED", "ACKNOWLEDGED", "DEFENDED", "ANSWERED", "WAITING_ADJUSTMENTS" ], "description": "Situação atual da contestação." }, "type": { "type": "string", "enum": [ "REFUND_REQUEST", "FRAUD", "REFUND_CANCELLED" ], "description": "Tipo da contestação: REFUND_REQUEST, FRAUD ou REFUND_CANCELLED." }, "reportedBy": { "type": "string", "enum": [ "DEBITED_PARTICIPANT", "CREDITED_PARTICIPANT" ], "description": "Lado que abriu a contestação: DEBITED_PARTICIPANT ou CREDITED_PARTICIPANT." }, "reportDetails": { "type": [ "string", "null" ], "description": "Motivo informado por quem abriu a contestação, no texto enviado pelo banco parceiro." }, "analysisResult": { "type": [ "string", "null" ], "enum": [ "AGREED", "DISAGREED", null ], "description": "Desfecho da análise: AGREED ou DISAGREED." }, "analysisDetails": { "type": [ "string", "null" ], "description": "Texto complementar sobre a decisão da análise, quando o banco parceiro envia essa informação." }, "reportedAt": { "type": "string", "format": "date-time", "description": "Momento em que a contestação foi aberta." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Prazo final para enviar a defesa desta contestação." }, "transaction": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "number", "description": "Valor da transação contestada, em reais com casas decimais." }, "payerName": { "type": [ "string", "null" ], "description": "Nome do pagador do Pix, conforme informado pelo provedor." }, "payerDocument": { "type": [ "string", "null" ], "description": "CPF ou CNPJ do pagador do Pix, conforme informado pelo provedor." }, "receiverName": { "type": [ "string", "null" ], "description": "Nome do recebedor do Pix, conforme informado pelo provedor." }, "receiverDocument": { "type": [ "string", "null" ], "description": "CPF ou CNPJ do recebedor do Pix, conforme informado pelo provedor." }, "endToEndId": { "type": [ "string", "null" ], "description": "Identificador fim a fim do Pix, informado pelo provedor na liquidação." } }, "description": "Resumo do Pix contestado." }, "defenseHistory": { "type": "array", "items": { "$ref": "#/components/schemas/DefenseHistoryEntry" }, "description": "Defesas já enviadas para esta contestação, com texto, status e anexos de cada uma." } } }, "Defense": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador da defesa." }, "defense": { "type": "string", "description": "Texto da defesa" }, "status": { "type": "string", "enum": [ "PENDING", "DEFENDED" ], "description": "Status da defesa" }, "infractionId": { "type": "string", "description": "Identifica a contestação a que a defesa pertence." }, "createdAt": { "type": "string", "format": "date-time", "description": "Momento em que a defesa foi registrada na PayZu, gravado junto com o envio dos anexos." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Momento da última alteração da defesa." }, "files": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome do arquivo enviado como anexo da defesa." }, "mimeType": { "type": "string", "description": "Tipo MIME do anexo, informado no upload, por exemplo application/pdf ou image/png." }, "size": { "type": "integer", "format": "int32", "description": "Tamanho do anexo em bytes." }, "url": { "type": [ "string", "null" ], "description": "URL assinada para download (expira em 9 minutos)." } } }, "description": "Anexos enviados junto com a defesa, com nome, tipo e tamanho em bytes." } } }, "InfractionListResponse": { "type": "object", "properties": { "infractions": { "type": "array", "items": { "$ref": "#/components/schemas/InfractionDetail" }, "description": "Contestações da página solicitada, cada uma no mesmo formato do detalhe." }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "format": "int32", "description": "Página devolvida, igual ao parâmetro page enviado na consulta; quando omitido, vale 1." }, "limit": { "type": "integer", "format": "int32", "description": "Tamanho de página aplicado na consulta; quando omitido vale 10 e o máximo aceito é 100." }, "totalItems": { "type": "integer", "format": "int32", "description": "Quantidade de infrações que atendem aos filtros." }, "totalPages": { "type": "integer", "format": "int32", "description": "Número de páginas para o limit informado, obtido de totalItems arredondado para cima." } }, "description": "Página, limite, total de itens e de páginas." } } }, "CallbackDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "ID único do callback" }, "url": { "type": "string", "description": "URL do webhook que recebeu o callback" }, "status": { "type": "number", "description": "Código de status HTTP da resposta" }, "transactionId": { "type": "string", "description": "ID da transação relacionada" }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em que o log do callback foi criado" }, "body": { "type": "object", "description": "Corpo da requisição enviado (JSON parseado)" }, "responseBody": { "type": "string", "description": "Corpo da resposta recebido (string)" }, "responseHeaders": { "type": "object", "description": "Cabeçalhos da resposta (JSON parseado)" }, "responseTime": { "type": "number", "description": "Tempo de ida e volta do webhook em milissegundos" } } }, "CallbackListResponse": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "description": "Página atual", "format": "int32" }, "limit": { "type": "integer", "description": "Itens por página", "format": "int32" }, "hasNextPage": { "type": "boolean", "description": "Indica se há uma próxima página" } }, "description": "Página e limite usados, e se há próxima página." }, "callbacks": { "type": "array", "items": { "$ref": "#/components/schemas/CallbackDetail" }, "description": "Array de logs de callback" } } }, "ReportJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identificador (UUID) do relatório, gerado no momento da solicitação." }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "COMPLETED", "FAILED" ], "description": "Andamento da geração: PENDING, RUNNING, COMPLETED ou FAILED." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em que a geração do relatório foi solicitada." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data e hora da última alteração no registro do relatório." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando o arquivo expira do armazenamento (normalmente 7 dias após a criação)" } } }, "PostPixRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "description": "Valor da cobrança.", "example": 10.9, "minimum": 1 }, "callbackUrl": { "type": "string", "description": "URL para notificações da transação.", "example": "https://webhook.cool/", "format": "uri" }, "generatedName": { "type": "string", "description": "Nome usado para montar a cobrança.", "example": "John Doe", "pattern": "^[a-zA-Z À-ÿ]+$", "minLength": 1 }, "generatedEmail": { "type": "string", "description": "E-mail usado para montar a cobrança.", "example": "john.doe@example.com", "format": "email" }, "generatedDocument": { "type": "string", "description": "CPF ou CNPJ do devedor da cobrança.", "example": "12345678901", "pattern": "^(\\d{11}|\\d{14})$" }, "expiresIn": { "type": "number", "description": "Segundos até o QR Code expirar.", "example": 600, "maximum": 172000 }, "clientReference": { "type": "string", "description": "Referência externa (pedido, fatura, etc.).", "example": "order_12345", "maxLength": 64 }, "virtualAccount": { "type": "string", "maxLength": 50, "description": "Subconta para separar lojas ou filiais.", "example": "loja-centro-01", "minLength": 1 } } }, "PostPixQrcodeReadRequest": { "type": "object", "required": [ "emv" ], "properties": { "emv": { "type": "string", "description": "A string do payload EMV do QR Code Pix.", "example": "00020101021226770014br.gov.bcb.pix2555api.payzu/pix/qr/v2/013318d6-2d7d-479e-8bb3-b5c7b9da688c5204000053039865802BR5916PAYZU 6007SAOPAULO6217051320260118278956304EC55", "minLength": 1 } } }, "PostWithdrawRequest": { "type": "object", "required": [ "amount", "pixKey", "pixType" ], "properties": { "amount": { "type": "number", "description": "Valor do saque.", "example": 2, "minimum": 0.01 }, "pixKey": { "type": "string", "description": "Chave Pix de destino.", "example": "teste@teste.com" }, "pixType": { "type": "string", "description": "Tipo da chave Pix.", "enum": [ "cpf", "cnpj", "phone", "email", "evp" ], "example": "email" }, "callbackUrl": { "type": "string", "description": "URL de webhook para atualizações de status.", "example": "https://webhook.cool/", "format": "uri" }, "clientReference": { "type": "string", "description": "Referência externa para este saque.", "example": "withdraw_98765", "maxLength": 64 }, "description": { "type": "string", "description": "Descrição opcional.", "example": "Weekly payout" }, "virtualAccount": { "type": "string", "maxLength": 50, "description": "Subconta para separar lojas ou filiais.", "example": "loja-centro-01", "minLength": 1 } } }, "PostWithdrawQrcodeRequest": { "type": "object", "required": [ "qrCode" ], "properties": { "qrCode": { "type": "string", "description": "Payload do Pix QR Code (formato EMV).", "example": "00020101021226770014br.gov.bcb.pix2555api.payzu/pix/qr/v2/013318d6-2d7d-479e-8bb3-b5c7b9da688c5204000053039865802BR5916PAYZU 6007SAOPAULO6217051320260118278956304EC55" }, "amount": { "type": "number", "description": "Valor do saque.", "example": 20, "minimum": 0.1 }, "callbackUrl": { "type": "string", "description": "URL de webhook para atualizações de status.", "example": "https://webhook.cool/", "format": "uri" }, "description": { "type": "string", "description": "Descrição opcional para o pagamento.", "example": "Pagamento via QR Code" }, "clientReference": { "type": "string", "description": "Referência externa para este saque.", "example": "order-123", "maxLength": 64 }, "virtualAccount": { "type": "string", "maxLength": 50, "description": "Subconta para separar lojas ou filiais.", "example": "loja-centro-01", "minLength": 1 } } }, "PostInfractionsDefenseRequest": { "type": "object", "required": [ "defense" ], "properties": { "defense": { "type": "string", "maxLength": 1000, "description": "Texto da defesa (máx: 1000 caracteres)", "example": "A cobranca foi autorizada pelo titular. Comprovante em anexo.", "minLength": 1 }, "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Arquivos de evidência (máx: 10MB no total)" } } }, "PostInternalTransferRequest": { "type": "object", "required": [ "payerAccountNumber", "receiverAccountNumber", "amount" ], "properties": { "payerAccountNumber": { "type": "string", "pattern": "^\\d{6}$", "description": "Conta do pagador.", "example": "000000" }, "receiverAccountNumber": { "type": "string", "pattern": "^\\d{6}$", "description": "Conta de destino.", "example": "987654" }, "amount": { "type": "number", "minimum": 0.01, "description": "Valor da transferência.", "example": 100.5 }, "description": { "type": "string", "maxLength": 500, "description": "Descrição opcional da transferência.", "example": "Pagamento referente a fatura #1234" }, "callbackUrl": { "type": "string", "format": "uri", "description": "URL para receber webhooks de atualização de transação.", "example": "https://webhook.cool/" }, "clientReference": { "type": "string", "maxLength": 64, "description": "Referência externa para idempotência / reconciliação.", "example": "transfer_abc_123" }, "virtualAccount": { "type": "string", "maxLength": 50, "description": "Subconta para separar lojas ou filiais.", "minLength": 1, "example": "loja-centro-01" } } }, "PostUserReportRequest": { "type": "object", "required": [ "dateFrom", "dateTo" ], "properties": { "dateFrom": { "type": "string", "format": "date-time", "example": "2026-07-01T00:00:00Z", "description": "Início do período do relatório." }, "dateTo": { "type": "string", "format": "date-time", "example": "2026-07-31T23:59:59Z", "description": "Fim do período do relatório." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELED", "WAITING_FOR_REFUND", "REFUNDED", "EXPIRED", "ERROR" ] }, "description": "Situações de transação que entram no arquivo." }, "type": { "type": "array", "items": { "type": "string", "enum": [ "DEPOSIT", "WITHDRAW", "COMMISSION" ] }, "description": "Tipos de transação que entram no arquivo." } } }, "ResendUserCallbacksRequest": { "type": "object", "required": [ "createdAtFrom", "createdAtTo" ], "properties": { "createdAtFrom": { "type": "string", "format": "date-time", "description": "Início do período. No máximo 30 dias atrás.", "example": "2026-08-05T00:00:00Z" }, "createdAtTo": { "type": "string", "format": "date-time", "description": "Fim do período. A janela entre início e fim não pode passar de 7 dias.", "example": "2026-08-11T23:59:59Z" }, "transactionIds": { "type": "array", "items": { "type": "string", "example": "PAYZU20260814T6NX1CV9MK000000" }, "description": "Restringe a IDs de transação específicos" }, "transactionTypes": { "type": "array", "items": { "type": "string", "enum": [ "DEPOSIT", "WITHDRAW", "COMMISSION" ] }, "description": "Filtra por tipo de transação" }, "transactionStatus": { "type": "array", "items": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELED", "WAITING_FOR_REFUND", "REFUNDED", "EXPIRED", "ERROR" ] }, "description": "Filtra por status da transação" }, "transactionEndToEndIds": { "type": "array", "items": { "type": "string", "example": "E12345678202608121200ABCDEFGHIJK" }, "description": "Restringe a IDs end-to-end Pix específicos" } } }, "ApiError": { "type": "object", "required": [ "status", "error", "errorCode", "message", "statusCode", "requestId" ], "properties": { "status": { "type": "string", "const": "ERROR", "description": "Marcador fixo de resposta de erro.", "example": "ERROR" }, "error": { "type": "string", "description": "Nome do status HTTP correspondente.", "example": "Bad Request" }, "errorCode": { "type": "string", "description": "Código de erro estável e legível por máquina, quando disponível.", "example": "PZV001" }, "message": { "type": "string", "description": "Mensagem de erro legível.", "example": "Dados inválidos. Verifique os campos informados." }, "statusCode": { "type": "integer", "description": "Código de status HTTP.", "example": 400 }, "requestId": { "type": "string", "description": "ID único de correlação da requisição (cuid).", "example": "cmbz0f8qk0001js04hp3e2n0f" }, "details": { "type": "array", "description": "Erros de validação por campo, quando aplicável.", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string", "description": "Caminho do campo rejeitado na validação, sem a barra inicial." }, "message": { "type": "string", "description": "Motivo da rejeição daquele campo, em português." } } } }, "retryAfterSeconds": { "type": "integer", "description": "Segundos a aguardar antes de tentar novamente.", "example": 30 } } }, "ProofResponse": { "type": "object", "properties": { "base64": { "type": "string", "description": "Comprovante em PDF como data URI base64, devolvido quando type=base64." } } }, "RefundRequest": { "type": "object", "properties": { "amount": { "type": "number", "description": "Valor a estornar.", "example": 30.5, "exclusiveMinimum": 0 }, "description": { "type": "string", "description": "Descrição livre do estorno.", "example": "Estorno solicitado pelo cliente" }, "clientReference": { "type": "string", "maxLength": 64, "description": "Chave de idempotência.", "example": "refund-2026-0001", "minLength": 1 } } }, "WebhookEventType": { "type": "string", "enum": [ "TRANSACTION_PENDING", "TRANSACTION_COMPLETED", "TRANSACTION_CANCELED", "TRANSACTION_WAITING_FOR_REFUND", "TRANSACTION_REFUNDED", "TRANSACTION_EXPIRED", "TRANSACTION_ERROR", "TRANSACTION_SUSPECTED_FRAUD", "TRANSACTION_SUSPECTED_FRAUD_REVERSAL", "INFRACTION_CHANGED" ], "description": "Evento de transação que dispara o webhook." }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "example": "cm3w7k1t40000q8f2r5b9x3ad", "description": "Id do webhook." }, "url": { "type": "string", "example": "https://sualoja.com.br/webhook", "description": "Endereço do seu sistema para onde a PayZu envia a notificação do evento." }, "active": { "type": "boolean", "example": true, "description": "Somente webhooks ativos recebem entregas." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "description": "Eventos assinados." }, "hasSecret": { "type": "boolean", "description": "Indica se o webhook tem segredo de assinatura HMAC.", "example": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em que o webhook foi cadastrado na conta." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data e hora da última alteração do webhook." } } }, "WebhookWithSecret": { "type": "object", "properties": { "id": { "type": "string", "example": "cm3w7k1t40000q8f2r5b9x3ad", "description": "Identificador do webhook." }, "url": { "type": "string", "example": "https://sualoja.com.br/webhook", "description": "Endereço que recebe as notificações." }, "active": { "type": "boolean", "example": true, "description": "Indica se o webhook já começa recebendo eventos." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "description": "Eventos assinados por este webhook." }, "hasSecret": { "type": "boolean", "example": true, "description": "Indica se o webhook tem segredo de assinatura." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data e hora da última alteração do webhook." }, "secret": { "type": [ "string", "null" ], "description": "Segredo de assinatura HMAC.", "example": "whsec_9f8a2b7c6d5e4f3a2b1c0d9e8f7a6b5c" } } }, "WebhookCreateRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "URL HTTPS que vai receber as notificações.", "example": "https://sualoja.com.br/webhook", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType", "enum": [ "TRANSACTION_PENDING", "TRANSACTION_COMPLETED", "TRANSACTION_CANCELED", "TRANSACTION_WAITING_FOR_REFUND", "TRANSACTION_REFUNDED", "TRANSACTION_EXPIRED", "TRANSACTION_ERROR", "TRANSACTION_SUSPECTED_FRAUD", "TRANSACTION_SUSPECTED_FRAUD_REVERSAL", "INFRACTION_CHANGED" ] }, "default": [], "description": "Eventos a assinar." }, "generateSecret": { "type": "boolean", "default": false, "description": "Gera um segredo de assinatura HMAC para este webhook." }, "active": { "type": "boolean", "description": "Se o webhook começa ativo.", "example": true } } }, "WebhookUpdateRequest": { "type": "object", "description": "Informe pelo menos um campo.", "properties": { "url": { "type": "string", "example": "https://sualoja.com.br/webhook", "description": "Novo endereço de entrega, que passa a valer nos disparos seguintes.", "format": "uri" }, "active": { "type": "boolean", "example": true, "description": "Liga ou pausa as entregas do webhook." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType", "enum": [ "TRANSACTION_PENDING", "TRANSACTION_COMPLETED", "TRANSACTION_CANCELED", "TRANSACTION_WAITING_FOR_REFUND", "TRANSACTION_REFUNDED", "TRANSACTION_EXPIRED", "TRANSACTION_ERROR", "TRANSACTION_SUSPECTED_FRAUD", "TRANSACTION_SUSPECTED_FRAUD_REVERSAL", "INFRACTION_CHANGED" ] }, "description": "Nova lista de eventos assinados, que substitui a anterior por inteiro." } }, "minProperties": 1 }, "RotateSecretResponse": { "type": "object", "properties": { "secret": { "type": "string", "description": "Segredo de assinatura HMAC.", "example": "whsec_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d" } } }, "SentWebhooksQuantity": { "type": "object", "properties": { "quantity": { "type": "integer", "example": 128, "description": "Total de entregas registradas." } } }, "WebhookListResponse": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" }, "description": "Webhooks cadastrados na conta." } } }, "SentWebhookDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador desta tentativa de entrega." }, "webhookId": { "type": [ "string", "null" ], "description": "Webhook que originou a entrega." }, "transactionId": { "type": "string", "description": "Transação Pix cujo evento foi notificado." }, "url": { "type": "string", "description": "Endereço para onde esta entrega foi feita, gravado no momento do disparo." }, "body": { "type": "string", "description": "Corpo enviado no disparo, em JSON serializado." }, "status": { "type": "integer", "description": "Status HTTP retornado pelo seu endpoint.", "example": 200 }, "responseHeaders": { "type": "string", "description": "Headers da resposta, em JSON serializado." }, "responseBody": { "type": "string", "description": "Corpo da resposta recebida." }, "error": { "type": [ "string", "null" ], "description": "Mensagem da falha na entrega." }, "responseTime": { "type": "integer", "description": "Tempo de resposta do seu endpoint, em milissegundos.", "example": 342 }, "eventType": { "type": [ "string", "null" ], "description": "Evento que disparou esta entrega, o mesmo valor enviado no cabeçalho X-Callback-Event." }, "createdAt": { "type": "string", "format": "date-time", "description": "Momento da tentativa de entrega." } } }, "BankStatement": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do lançamento de saldo." }, "amount": { "type": "number", "description": "Valor do lançamento." }, "operation": { "type": "string", "enum": [ "INCREMENT", "DECREMENT" ], "description": "INCREMENT credita o saldo, DECREMENT debita." }, "reason": { "type": "string", "description": "Motivo do lançamento no extrato." }, "balanceType": { "type": "string", "enum": [ "AVAILABLE", "BLOCKED" ], "description": "Saldo movimentado: AVAILABLE ou BLOCKED." }, "previousBalanceAvailable": { "type": "number", "description": "Saldo livre para uso que a conta tinha, em reais, imediatamente antes deste lançamento." }, "previousBalanceBlocked": { "type": "number", "description": "Saldo bloqueado antes do lançamento, em reais." }, "newBalanceAvailable": { "type": "number", "description": "Saldo disponível depois do lançamento, em reais." }, "newBalanceBlocked": { "type": "number", "description": "Saldo bloqueado depois do lançamento, em reais." }, "transactionId": { "type": [ "string", "null" ], "description": "Transação que originou o lançamento." }, "infractionId": { "type": [ "string", "null" ], "description": "Infração relacionada ao lançamento." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em que a movimentação de saldo foi registrada." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data e hora da última alteração do registro." } } }, "BankStatementListResponse": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "description": "Página devolvida, igual ao parâmetro page enviado na consulta; quando omitido, vale 1." }, "limit": { "type": "integer", "description": "Tamanho de página aplicado na consulta; quando omitido vale 10 e o máximo aceito é 100." }, "hasNextPage": { "type": "boolean", "description": "Indica se existe página seguinte, detectada buscando um item além do limit." } }, "description": "Página e limite usados, e se há próxima página." }, "bankStatements": { "type": "array", "items": { "$ref": "#/components/schemas/BankStatement" }, "description": "Lançamentos da página consultada." } } }, "DepositPending": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do depósito pendente." }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED", "REJECTED", "EXPIRED", "COMPLETED" ], "description": "Situação do depósito: PENDING, COMPLETED ou REJECTED." }, "amount": { "type": "number", "description": "Valor recebido." }, "payerDocument": { "type": "string", "description": "CNPJ de quem enviou o Pix." }, "payerName": { "type": [ "string", "null" ], "description": "Nome de quem enviou o Pix." }, "payerAccountNumber": { "type": [ "string", "null" ], "description": "Número da conta do pagador dentro da plataforma." }, "payerInstitutionIspb": { "type": [ "string", "null" ], "description": "Código ISPB da instituição de onde saiu o Pix." }, "payerInstitutionName": { "type": [ "string", "null" ], "description": "Nome da instituição de onde o Pix saiu." }, "receiverDocument": { "type": [ "string", "null" ], "description": "CPF ou CNPJ da conta que recebeu o Pix." }, "receiverName": { "type": [ "string", "null" ], "description": "Nome da conta que recebeu o Pix." }, "receiverAccountNumber": { "type": [ "string", "null" ], "description": "Número da sua conta na PayZu que receberá o crédito caso o depósito seja aprovado." }, "receiverInstitutionIspb": { "type": [ "string", "null" ], "description": "Código ISPB da instituição que recebeu o Pix." }, "receiverInstitutionName": { "type": [ "string", "null" ], "description": "Nome da instituição em que o Pix foi liquidado do lado de quem recebeu." }, "endToEndId": { "type": "string", "description": "Identificador ponta a ponta do Pix." }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Data e hora da liquidação do Pix." }, "pixKey": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ], "description": "Texto livre que acompanharia o Pix." }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Data e hora da aprovação do depósito." }, "rejectedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Data e hora da recusa do depósito." }, "rejectionReason": { "type": [ "string", "null" ], "description": "Motivo da recusa do depósito." }, "transactionId": { "type": [ "string", "null" ], "description": "Transação de depósito criada na aprovação." }, "createdAt": { "type": "string", "format": "date-time", "description": "Momento em que o Pix recebido foi registrado, antes do crédito." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Momento da última alteração do registro, que muda quando o depósito é aprovado ou recusado." } } }, "DepositPendingListResponse": { "type": "object", "properties": { "page": { "type": "integer", "description": "Página devolvida nesta resposta." }, "limit": { "type": "integer", "description": "Quantidade máxima de registros por página usada nesta consulta." }, "hasNextPage": { "type": "boolean", "description": "Vem true quando ainda existe registro depois desta página." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DepositPending" }, "description": "Depósitos pendentes desta página, ordenados da criação mais recente para a mais antiga." } } }, "SummaryStatus": { "type": "object", "properties": { "count": { "type": "integer", "description": "Quantidade de transações nessa situação dentro do período." }, "amount": { "type": "number", "description": "Soma dos valores dessas transações." }, "serviceFeeCharged": { "type": "number", "description": "Soma das taxas cobradas nessas transações, em reais." } } }, "SummaryBlock": { "type": "object", "properties": { "totalAmount": { "type": "number", "description": "Soma dos valores no período." }, "totalTransactions": { "type": "integer", "description": "Quantidade de transações desse tipo no período, também somando todos os status." }, "statuses": { "type": "object", "properties": { "pending": { "$ref": "#/components/schemas/SummaryStatus", "description": "Contagem e soma dos valores, em reais, das transações com status PENDING no período consultado." }, "completed": { "$ref": "#/components/schemas/SummaryStatus", "description": "Contagem e soma das transações concluídas, em reais." }, "canceled": { "$ref": "#/components/schemas/SummaryStatus", "description": "Contagem e soma das transações canceladas, em reais." }, "expired": { "$ref": "#/components/schemas/SummaryStatus", "description": "Contagem e soma das transações expiradas, em reais." }, "refunded": { "$ref": "#/components/schemas/SummaryStatus", "description": "Contagem e valor estornado no período, em reais." } }, "description": "Totais por status no período." }, "grouped": { "type": "array", "description": "Presente apenas quando grouped=true.", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Início do intervalo, truncado por dia ou por hora conforme o groupBy." }, "amount": { "type": "number", "description": "Soma dos valores, em reais, das transações do intervalo." } } } } } }, "Summary": { "type": "object", "properties": { "totalTransactions": { "type": "integer", "description": "Quantidade de transações no período." }, "deposit": { "$ref": "#/components/schemas/SummaryBlock", "description": "Resumo das entradas da conta no período, ou seja, das transações do tipo DEPOSIT." }, "withdraw": { "$ref": "#/components/schemas/SummaryBlock", "description": "Resumo das saídas da conta no período, ou seja, das transações do tipo WITHDRAW." }, "commission": { "$ref": "#/components/schemas/SummaryBlock", "description": "Resumo das comissões creditadas à conta no período (transações do tipo COMMISSION)." } } }, "DictConsultResponse": { "type": "object", "properties": { "pixKey": { "type": "string", "description": "Chave Pix normalizada." }, "name": { "type": "string", "description": "Nome do titular da chave conforme devolvido pela instituição consultada." }, "document": { "type": "string", "description": "CPF/CNPJ mascarado do titular da chave." }, "personType": { "type": "string", "enum": [ "PF", "PJ" ], "description": "Indica se o titular da chave é pessoa física ou jurídica, normalmente PF ou PJ." }, "accountType": { "type": "string" }, "institutionIspb": { "type": "string", "description": "Código ISPB da instituição da conta." }, "institutionName": { "type": "string", "description": "Nome da instituição onde a conta do titular está registrada, do jeito que a consulta devolve." } } }, "DefenseHistoryEntry": { "type": "object", "description": "Defesa registrada no histórico da infração, sem o campo infractionId.", "properties": { "id": { "type": "string", "description": "Identificador da defesa." }, "defense": { "type": "string", "description": "Texto da defesa" }, "status": { "type": "string", "enum": [ "PENDING", "DEFENDED" ], "description": "Status da defesa" }, "createdAt": { "type": "string", "format": "date-time", "description": "Momento em que a defesa foi registrada na PayZu, gravado junto com o envio dos anexos." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Momento da última alteração da defesa." }, "files": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome do arquivo enviado como anexo da defesa." }, "mimeType": { "type": "string", "description": "Tipo MIME do anexo, informado no upload, por exemplo application/pdf ou image/png." }, "size": { "type": "integer", "format": "int32", "description": "Tamanho do anexo em bytes." }, "url": { "type": [ "string", "null" ], "description": "URL assinada para download (expira em 9 minutos)." } } }, "description": "Anexos enviados junto com a defesa, com nome, tipo e tamanho em bytes." } } }, "ReportJobDetail": { "type": "object", "description": "Job de relatório com os filtros usados e o total de linhas escritas.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identificador (UUID) do relatório, gerado no momento da solicitação." }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "COMPLETED", "FAILED" ], "description": "Andamento da geração: PENDING, RUNNING, COMPLETED ou FAILED." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em que a geração do relatório foi solicitada." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data e hora da última alteração no registro do relatório." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando o arquivo expira do armazenamento (normalmente 7 dias após a criação)" }, "params": { "type": "object", "additionalProperties": true, "description": "Filtros usados na criação do relatório." }, "writtenRows": { "type": "integer", "description": "Linhas já escritas no arquivo." } } }, "ReportJobAccepted": { "type": "object", "description": "Job de relatório recém-enfileirado.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identificador (UUID) do relatório, gerado no momento da solicitação." }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "COMPLETED", "FAILED" ], "description": "Andamento da geração: PENDING, RUNNING, COMPLETED ou FAILED." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em que a geração do relatório foi solicitada." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data e hora da última alteração no registro do relatório." }, "params": { "type": "object", "additionalProperties": true, "description": "Filtros usados na criação do relatório." }, "writtenRows": { "type": "integer", "description": "Linhas já escritas no arquivo." }, "storageExpiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Data em que o arquivo do relatório expira." } } }, "SentWebhookDetailResponse": { "type": "object", "required": [ "sentWebhookDetails" ], "properties": { "sentWebhookDetails": { "$ref": "#/components/schemas/SentWebhookDetail" } } }, "EnqueuedCallbackItem": { "type": "object", "properties": { "transactionId": { "type": "string", "description": "Transação cujo callback foi enfileirado.", "example": "PAYZU20260811K7M2X9QP4T000000" }, "webhookId": { "type": "string", "description": "Webhook que recebe a entrega.", "example": "cm3w7k1t40000q8f2r5b9x3ad" }, "eventType": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventType" } ], "description": "Evento que disparou o callback, quando o log registra." } } }, "EnqueuedCallback": { "type": "object", "properties": { "enqueued": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total de callbacks enviados para enfileiramento. Não é limitado pelo tamanho de items.", "example": 12 }, "truncated": { "type": "boolean", "description": "true quando items lista apenas parte dos callbacks. O reenvio cobre todos mesmo assim.", "example": false }, "items": { "type": "array", "description": "Callbacks enfileirados, no máximo 500 entradas.", "items": { "$ref": "#/components/schemas/EnqueuedCallbackItem" } } } } } }, "CallbackSecretResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmação do segredo criado." }, "secret": { "type": "string", "description": "Segredo de callback, 43 caracteres base64url. Guarde: não há rota para lê-lo de novo.", "example": "Zk8Qk1Yb3nS6xPwT2cVrJ9dLmHgA4eN7uKfR0iXsBqE" } } }, "RotateCallbackSecretResponse": { "type": "object", "properties": { "secret": { "type": "string", "description": "Segredo de callback, 43 caracteres base64url. Guarde: não há rota para lê-lo de novo.", "example": "Zk8Qk1Yb3nS6xPwT2cVrJ9dLmHgA4eN7uKfR0iXsBqE" } } } } }, "externalDocs": { "description": "Documentação completa", "url": "https://docs.payzu.com.br/docs/pix-processamento" } }