{ "openapi": "3.1.0", "info": { "version": "1.0.0", "title": "PayZu API Conta Digital", "description": "API da Conta Digital PayZu: cobranças Pix, saques, pagamento de Pix copia e cola, transferências entre contas, chaves Pix, extrato, contestações MED e webhooks.\n\nValores em centavos, percentuais em basis points (`150` = 1,5%), datas em ISO 8601 (UTC). Toda operação acontece na conta da credencial.\n\nComo autenticar: [Autenticação](https://docs.payzu.com.br/docs/conta-digital/authentication). Guias e referência completa em [docs.payzu.com.br/docs/conta-digital](https://docs.payzu.com.br/docs/conta-digital)." }, "servers": [ { "url": "https://api.hub.payzu.com.br/api/v1", "description": "Produção" } ], "tags": [ { "name": "Authentication", "description": "Troca da credencial por token de acesso." }, { "name": "Charges", "description": "Cobranças Pix: criar, consultar, listar, comprovante e estorno." }, { "name": "Withdrawals", "description": "Saques para chave Pix." }, { "name": "Pix", "description": "Leitura e pagamento de Pix copia e cola e consulta de destinatário." }, { "name": "Pix Keys", "description": "Chaves Pix da conta." }, { "name": "Internal Transfers", "description": "Transferências entre contas PayZu." }, { "name": "Deposits", "description": "Pix recebido sem cobrança." }, { "name": "Account", "description": "Saldo, extrato, limites e métricas." }, { "name": "Infractions", "description": "Contestações MED abertas contra a conta." }, { "name": "Webhooks", "description": "Endpoints de webhook e segredo de callback." }, { "name": "Status", "description": "Saúde do serviço." }, { "name": "Webhook Events", "description": "Webhooks que a PayZu envia ao seu endpoint, um por evento." } ], "paths": { "/oauth/token": { "post": { "summary": "Obter token de acesso", "description": "Troca a credencial por um token de acesso válido por 15 minutos. Envie `client_id` e `client_secret` no header `Authorization: Basic` ou no corpo, em `application/x-www-form-urlencoded` ou JSON. Há limite de trocas por `client_id` e IP, e a lista de IPs da credencial vale aqui também.", "operationId": "post_oauth_token", "tags": [ "Authentication" ], "security": [ { "BasicAuth": [] }, {} ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" }, "example": { "grant_type": "client_credentials" } }, "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" }, "example": { "grant_type": "client_credentials" } } } }, "responses": { "200": { "description": "Token emitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthToken" }, "examples": { "Token emitido": { "summary": "Token emitido", "value": { "access_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..mQ3Zy1hbVhpbXBsZQ.ZXhlbXBsbw.c2lnbmF0dXJl", "token_type": "Bearer", "expires_in": 900, "scope": "PAYMENT_WRITE PAYMENT_READ STATEMENT_READ" } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_UNSUPPORTED_GRANT_TYPE": { "summary": "TOKEN_UNSUPPORTED_GRANT_TYPE", "value": { "message": "grant_type não suportado. Use client_credentials.", "code": "TOKEN_UNSUPPORTED_GRANT_TYPE" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "429": { "description": "Limite de requisições excedido.", "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AUTH_TOO_MANY_REQUESTS": { "summary": "AUTH_TOO_MANY_REQUESTS", "value": { "message": "Muitas tentativas. Tente novamente em alguns minutos.", "code": "AUTH_TOO_MANY_REQUESTS", "details": { "retryAfterSeconds": 12 } } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.hub.payzu.com.br/api/v1/oauth/token' \\\n --user \"$PAYZU_CLIENT_ID:$PAYZU_CLIENT_SECRET\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"grant_type\": \"client_credentials\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/oauth/token';\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Basic ${Buffer.from(`${process.env.PAYZU_CLIENT_ID}:${process.env.PAYZU_CLIENT_SECRET}`).toString('base64')}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n grant_type: 'client_credentials'\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.hub.payzu.com.br/api/v1/oauth/token',\n auth=(os.environ['PAYZU_CLIENT_ID'], os.environ['PAYZU_CLIENT_SECRET']),\n headers={\n 'Content-Type': 'application/json',\n },\n json={\n 'grant_type': 'client_credentials'\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/payment": { "post": { "summary": "Criar cobrança Pix", "description": "Escopo: `PAYMENT_WRITE`.\n\nGera uma cobrança e devolve o Pix copia e cola que o seu cliente vai pagar. O código vem em `pix.qrCodeText`. A cobrança nasce `PENDING`; o saldo muda quando o pagamento é confirmado, e a confirmação chega pelo webhook `PAYMENT_PAID`. Limite de requisições: 60 por minuto por credencial e 120 por conta.", "operationId": "post_payment", "tags": [ "Charges" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayment" }, "example": { "amount": 1500, "method": "PIX", "description": "Pedido 4821", "externalRef": "pedido-4821", "customer": { "name": "Maria Souza", "document": "52998224725", "email": "maria.souza@exemplo.com", "phone": "+5511999998888" }, "metadata": { "pedido": "4821", "canal": "checkout-web" } } } } }, "responses": { "200": { "description": "O `externalRef` já tinha uma cobrança com os mesmos dados; ela é devolvida e nada é criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "Cobrança existente": { "summary": "Cobrança existente", "value": { "id": "hubp-20261005K7Q2M9XB4T127431", "method": "PIX", "status": "PENDING", "amount": 1500, "description": "Pedido 4821", "serviceFee": 105, "netAmount": 1395, "refundedAmount": 0, "refundFee": 0, "refundInProgressAmount": 0, "refundableAmount": 0, "openInfractionProtocol": null, "externalRef": "pedido-4821", "callbackUrl": null, "createdAt": "2026-10-05T14:32:05.123Z", "paidAt": null, "refundedAt": null, "pix": { "qrCodeText": "00020126580014br.gov.bcb.pix0136b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03520400005303986540515.005802BR5912LOJA EXEMPLO6009SAO PAULO62070503***63041EC4", "qrCodeUrl": null, "qrCodeBase64": null, "conciliationId": null }, "customer": { "name": "Maria Souza", "document": "52998224725", "email": "maria.souza@exemplo.com", "phone": "+5511999998888" }, "payer": null, "refunds": [] } } } } } }, "201": { "description": "Cobrança criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "Cobrança criada": { "summary": "Cobrança criada", "value": { "id": "hubp-20261005K7Q2M9XB4T127431", "method": "PIX", "status": "PENDING", "amount": 1500, "description": "Pedido 4821", "serviceFee": 105, "netAmount": 1395, "refundedAmount": 0, "refundFee": 0, "refundInProgressAmount": 0, "refundableAmount": 0, "openInfractionProtocol": null, "externalRef": "pedido-4821", "callbackUrl": null, "createdAt": "2026-10-05T14:32:05.123Z", "paidAt": null, "refundedAt": null, "pix": { "qrCodeText": "00020126580014br.gov.bcb.pix0136b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03520400005303986540515.005802BR5912LOJA EXEMPLO6009SAO PAULO62070503***63041EC4", "qrCodeUrl": null, "qrCodeBase64": null, "conciliationId": null }, "customer": { "name": "Maria Souza", "document": "52998224725", "email": "maria.souza@exemplo.com", "phone": "+5511999998888" }, "payer": null, "refunds": [] } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID", "details": { "customer": { "document": "Informe um CPF ou CNPJ válido." } } } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PAYMENT_DISABLED": { "summary": "PAYMENT_DISABLED", "value": { "message": "Pagamento desabilitado para esta conta.", "code": "PAYMENT_DISABLED" } }, "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "PAYMENT_WRITE" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "409": { "description": "Conflito com o estado atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PAYMENT_EXTERNAL_REF_MISMATCH": { "summary": "PAYMENT_EXTERNAL_REF_MISMATCH", "value": { "message": "Já existe uma cobrança com esta referência, e os dados enviados não conferem com os dela.", "code": "PAYMENT_EXTERNAL_REF_MISMATCH", "details": { "fields": [ "amount" ] } } } } } } }, "412": { "description": "Falta um passo antes desta operação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PAYMENT_CREATION_IN_FLIGHT": { "summary": "PAYMENT_CREATION_IN_FLIGHT", "value": { "message": "Uma cobrança com esta referência está sendo criada agora. Repita em instantes.", "code": "PAYMENT_CREATION_IN_FLIGHT", "details": { "externalRef": "pedido-4821" } } }, "CALLBACK_SECRET_MISSING": { "summary": "CALLBACK_SECRET_MISSING", "value": { "message": "Gere o segredo de callback da conta antes de informar uma callbackUrl.", "code": "CALLBACK_SECRET_MISSING" } }, "ACCOUNT_NOT_OPERABLE": { "summary": "ACCOUNT_NOT_OPERABLE", "value": { "message": "Esta conta não está ativa e não pode movimentar dinheiro.", "code": "ACCOUNT_NOT_OPERABLE", "details": { "status": "CLOSED" } } }, "PROVIDER_NOT_PROVISIONED": { "summary": "PROVIDER_NOT_PROVISIONED", "value": { "message": "Esta conta ainda não terminou de ser aberta.", "code": "PROVIDER_NOT_PROVISIONED" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PAYMENT_BELOW_MINIMUM": { "summary": "PAYMENT_BELOW_MINIMUM", "value": { "message": "O valor é inferior ao mínimo permitido.", "code": "PAYMENT_BELOW_MINIMUM", "details": { "min": 100 } } }, "PAYMENT_ABOVE_MAXIMUM": { "summary": "PAYMENT_ABOVE_MAXIMUM", "value": { "message": "O valor excede o máximo permitido.", "code": "PAYMENT_ABOVE_MAXIMUM", "details": { "max": 1000000 } } }, "PAYMENT_AMOUNT_NOT_ABOVE_FEE": { "summary": "PAYMENT_AMOUNT_NOT_ABOVE_FEE", "value": { "message": "O valor da cobrança precisa ser maior que a tarifa de recebimento.", "code": "PAYMENT_AMOUNT_NOT_ABOVE_FEE", "details": { "amount": 80, "fee": 85 } } }, "ACCOUNT_HELD_BY_STAFF": { "summary": "ACCOUNT_HELD_BY_STAFF", "value": { "message": "Esta conta está retida por decisão do suporte e não pode realizar operações até a liberação.", "code": "ACCOUNT_HELD_BY_STAFF" } }, "ACCOUNT_BLOCKED_BY_PROVIDER": { "summary": "ACCOUNT_BLOCKED_BY_PROVIDER", "value": { "message": "A conta tem um bloqueio na instituição parceira que impede esta operação até o desbloqueio.", "code": "ACCOUNT_BLOCKED_BY_PROVIDER", "details": { "operation": "PIX_IN" } } }, "PROVIDER_OPERATION_UNAVAILABLE": { "summary": "PROVIDER_OPERATION_UNAVAILABLE", "value": { "message": "Operação indisponível para esta conta no momento.", "code": "PROVIDER_OPERATION_UNAVAILABLE" } } } } } }, "429": { "description": "Limite de requisições excedido.", "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AUTH_TOO_MANY_REQUESTS": { "summary": "AUTH_TOO_MANY_REQUESTS", "value": { "message": "Muitas tentativas. Tente novamente em alguns minutos.", "code": "AUTH_TOO_MANY_REQUESTS", "details": { "retryAfterSeconds": 12 } } } } } } }, "502": { "description": "O banco não respondeu ou recusou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PROVIDER_UNAVAILABLE": { "summary": "PROVIDER_UNAVAILABLE", "value": { "message": "Não houve resposta a tempo. Tente de novo em instantes.", "code": "PROVIDER_UNAVAILABLE", "details": { "status": null, "reason": null } } }, "PROVIDER_REFUSED": { "summary": "PROVIDER_REFUSED", "value": { "message": "Esta operação foi recusada. Confira os dados enviados.", "code": "PROVIDER_REFUSED", "details": { "status": 422, "reason": "Operação recusada pelo banco." } } } } } } }, "503": { "description": "Serviço de consulta ou limitador indisponível; nada foi feito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_UNAVAILABLE": { "summary": "RATE_LIMIT_UNAVAILABLE", "value": { "message": "Proteção de limite indisponível. Tente novamente em instantes.", "code": "RATE_LIMIT_UNAVAILABLE" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/payment' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"amount\": 1500,\n \"method\": \"PIX\",\n \"description\": \"Pedido 4821\",\n \"externalRef\": \"pedido-4821\",\n \"customer\": {\n \"name\": \"Maria Souza\",\n \"document\": \"52998224725\",\n \"email\": \"maria.souza@exemplo.com\",\n \"phone\": \"+5511999998888\"\n },\n \"metadata\": {\n \"pedido\": \"4821\",\n \"canal\": \"checkout-web\"\n }\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/payment';\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: 1500,\n method: 'PIX',\n description: 'Pedido 4821',\n externalRef: 'pedido-4821',\n customer: {\n name: 'Maria Souza',\n document: '52998224725',\n email: 'maria.souza@exemplo.com',\n phone: '+5511999998888'\n },\n metadata: {\n pedido: '4821',\n canal: 'checkout-web'\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.hub.payzu.com.br/api/v1/transactions/payment',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'amount': 1500,\n 'method': 'PIX',\n 'description': 'Pedido 4821',\n 'externalRef': 'pedido-4821',\n 'customer': {\n 'name': 'Maria Souza',\n 'document': '52998224725',\n 'email': 'maria.souza@exemplo.com',\n 'phone': '+5511999998888'\n },\n 'metadata': {\n 'pedido': '4821',\n 'canal': 'checkout-web'\n }\n },\n)\n\nprint(response.json())" } ] }, "get": { "summary": "Listar cobranças", "description": "Escopo: `PAYMENT_READ`.\n\nDevolve as cobranças da conta, da mais recente para a mais antiga, paginadas por cursor.", "operationId": "get_payments", "tags": [ "Charges" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Itens por página, de 1 a 100." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" }, "description": "`nextCursor` da página anterior." }, { "in": "query", "name": "method", "required": false, "schema": { "type": "string", "enum": [ "PIX" ] }, "description": "Meio de pagamento." }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "PAID", "REFUNDED", "EXPIRED" ] }, "description": "Estado da cobrança." }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string" }, "description": "Início do período, pela data de criação. ISO 8601 ou `AAAA-MM-DD`; data sem hora vale o dia inteiro no horário de Brasília." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string" }, "description": "Fim do período, pela data de criação. ISO 8601 ou `AAAA-MM-DD`; data sem hora vale o dia inteiro no horário de Brasília." }, { "in": "query", "name": "search", "required": false, "schema": { "type": "string", "minLength": 3, "maxLength": 120 }, "description": "Id, nome ou documento do cliente informado na criação. De 3 a 120 caracteres." }, { "in": "query", "name": "externalRef", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "pedido-4821", "description": "Sua referência, exata." } ], "responses": { "200": { "description": "Página de cobranças.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentList" }, "examples": { "Página de cobranças": { "summary": "Página de cobranças", "value": { "data": [ { "id": "hubp-20261005K7Q2M9XB4T127431", "method": "PIX", "status": "PAID", "amount": 1500, "netAmount": 1395, "refundedAmount": 0, "refundInProgressAmount": 0, "description": "Pedido 4821", "payerName": "Maria Souza", "payerDocument": "52998224725", "createdAt": "2026-10-05T14:32:05.123Z", "paidAt": "2026-10-05T14:33:10.004Z" } ], "nextCursor": "cmu2wbljx0000e8gtlic8q1gi" } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } }, "REQUEST_UNKNOWN_QUERY_PARAM": { "summary": "REQUEST_UNKNOWN_QUERY_PARAM", "value": { "message": "A requisição tem um parâmetro de busca que esta rota não conhece.", "code": "REQUEST_UNKNOWN_QUERY_PARAM", "details": { "unknownParams": [ "page" ], "accepted": [ "cursor", "dateFrom", "dateTo", "externalRef", "limit", "method", "search", "status" ] } } }, "PAYMENT_INVALID_CURSOR": { "summary": "PAYMENT_INVALID_CURSOR", "value": { "message": "Cursor de paginação inválido — recomece da primeira página.", "code": "PAYMENT_INVALID_CURSOR" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "PAYMENT_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/payment' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/payment';\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.hub.payzu.com.br/api/v1/transactions/payment',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/payment/{paymentId}": { "get": { "summary": "Consultar cobrança", "description": "Escopo: `PAYMENT_READ`.\n\nDevolve uma cobrança com o Pix copia e cola, o pagador e os estornos. Aceita o `id` da cobrança e o `paymentId` dos webhooks.", "operationId": "get_payment", "tags": [ "Charges" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "paymentId", "required": true, "schema": { "type": "string" }, "example": "hubp-20261005K7Q2M9XB4T127431", "description": "Identificador da cobrança." } ], "responses": { "200": { "description": "Cobrança.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "Cobrança paga": { "summary": "Cobrança paga", "value": { "id": "hubp-20261005K7Q2M9XB4T127431", "method": "PIX", "status": "PAID", "amount": 1500, "description": "Pedido 4821", "serviceFee": 105, "netAmount": 1395, "refundedAmount": 0, "refundFee": 0, "refundInProgressAmount": 0, "refundableAmount": 1500, "openInfractionProtocol": null, "externalRef": "pedido-4821", "callbackUrl": null, "createdAt": "2026-10-05T14:32:05.123Z", "paidAt": "2026-10-05T14:33:10.004Z", "refundedAt": null, "pix": { "qrCodeText": "00020126580014br.gov.bcb.pix0136b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03520400005303986540515.005802BR5912LOJA EXEMPLO6009SAO PAULO62070503***63041EC4", "qrCodeUrl": null, "qrCodeBase64": null, "conciliationId": "E99999999202610051433a1b2c3d4e5f" }, "customer": { "name": "Maria Souza", "document": "52998224725", "email": "maria.souza@exemplo.com", "phone": "+5511999998888" }, "payer": { "name": "Maria Souza", "document": "***.982.247-**", "bankName": "Banco Exemplo S.A." }, "refunds": [] } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "PAYMENT_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PAYMENT_NOT_FOUND": { "summary": "PAYMENT_NOT_FOUND", "value": { "message": "Pagamento não encontrado.", "code": "PAYMENT_NOT_FOUND" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/payment/hubp-20261005K7Q2M9XB4T127431' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/payment/hubp-20261005K7Q2M9XB4T127431';\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.hub.payzu.com.br/api/v1/transactions/payment/hubp-20261005K7Q2M9XB4T127431',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/payment/{paymentId}/receipt": { "get": { "summary": "Comprovante da cobrança", "description": "Escopo: `PAYMENT_READ`.\n\nDevolve o comprovante da cobrança em PDF, codificado em base64. Só para cobrança `PAID` ou `REFUNDED`.", "operationId": "get_payment_receipt", "tags": [ "Charges" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "paymentId", "required": true, "schema": { "type": "string" }, "example": "hubp-20261005K7Q2M9XB4T127431", "description": "Identificador da cobrança." } ], "responses": { "200": { "description": "Comprovante.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "examples": { "Comprovante": { "summary": "Comprovante", "value": { "filename": "comprovante-pix-hubp-20261005K7Q2M9XB4T127431.pdf", "contentType": "application/pdf", "fileBase64": "JVBERi0xLjcKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nCvkMlAwUDC1NNUzMjNSMDEz" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "PAYMENT_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PAYMENT_NOT_FOUND": { "summary": "PAYMENT_NOT_FOUND", "value": { "message": "Pagamento não encontrado.", "code": "PAYMENT_NOT_FOUND" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RECEIPT_NOT_SETTLED": { "summary": "RECEIPT_NOT_SETTLED", "value": { "message": "Comprovante disponível só para operação concluída.", "code": "RECEIPT_NOT_SETTLED", "details": { "status": "PENDING" } } }, "RECEIPT_MISSING_END_TO_END": { "summary": "RECEIPT_MISSING_END_TO_END", "value": { "message": "Esta operação ainda não tem end-to-end, e sem ele o comprovante não prova nada. Tente de novo em alguns minutos.", "code": "RECEIPT_MISSING_END_TO_END" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/payment/hubp-20261005K7Q2M9XB4T127431/receipt' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/payment/hubp-20261005K7Q2M9XB4T127431/receipt';\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.hub.payzu.com.br/api/v1/transactions/payment/hubp-20261005K7Q2M9XB4T127431/receipt',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/payment/{paymentId}/refund": { "post": { "summary": "Estornar cobrança", "description": "Escopo: `REFUND`.\n\nDevolve ao pagador todo ou parte do valor de uma cobrança paga. Sem `amount`, devolve o que resta; a tarifa de estorno é somada por cima. O valor sai do saldo disponível na hora do pedido e volta se o estorno falhar. Um estorno de cada vez por cobrança; o resultado chega pelos webhooks `REFUND_COMPLETED` ou `REFUND_FAILED`. Conta no limite de requisições do saque. Não aceita `Idempotency-Key`: num `502`, consulte a cobrança antes de repetir.", "operationId": "post_payment_refund", "tags": [ "Charges" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "paymentId", "required": true, "schema": { "type": "string" }, "example": "hubp-20261005K7Q2M9XB4T127431", "description": "Identificador da cobrança." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefund" }, "example": { "amount": 1000 } } } }, "responses": { "200": { "description": "A cobrança atualizada, com o estorno em `refunds`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "Estorno a caminho": { "summary": "Estorno a caminho", "value": { "id": "hubp-20261005K7Q2M9XB4T127431", "method": "PIX", "status": "PAID", "amount": 1500, "description": "Pedido 4821", "serviceFee": 105, "netAmount": 1395, "refundedAmount": 0, "refundFee": 0, "refundInProgressAmount": 1000, "refundableAmount": 0, "openInfractionProtocol": null, "externalRef": "pedido-4821", "callbackUrl": null, "createdAt": "2026-10-05T14:32:05.123Z", "paidAt": "2026-10-05T14:33:10.004Z", "refundedAt": null, "pix": { "qrCodeText": "00020126580014br.gov.bcb.pix0136b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03520400005303986540515.005802BR5912LOJA EXEMPLO6009SAO PAULO62070503***63041EC4", "qrCodeUrl": null, "qrCodeBase64": null, "conciliationId": "E99999999202610051433a1b2c3d4e5f" }, "customer": { "name": "Maria Souza", "document": "52998224725", "email": "maria.souza@exemplo.com", "phone": "+5511999998888" }, "payer": { "name": "Maria Souza", "document": "***.982.247-**", "bankName": "Banco Exemplo S.A." }, "refunds": [ { "id": "cmu7r2f9k000301s6abcd5678", "status": "SENT", "amount": 1000, "serviceFee": 100, "totalDebited": 1100, "endToEndId": null, "rejectedReason": null, "requestedAt": "2026-10-06T09:15:00.000Z", "settledAt": null, "releasedAt": null } ] } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "REFUND_DISABLED": { "summary": "REFUND_DISABLED", "value": { "message": "Estorno desabilitado para esta conta.", "code": "REFUND_DISABLED" } }, "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "REFUND" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PAYMENT_NOT_FOUND": { "summary": "PAYMENT_NOT_FOUND", "value": { "message": "Pagamento não encontrado.", "code": "PAYMENT_NOT_FOUND" } } } } } }, "412": { "description": "Falta um passo antes desta operação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ACCOUNT_NOT_OPERABLE": { "summary": "ACCOUNT_NOT_OPERABLE", "value": { "message": "Esta conta não está ativa e não pode movimentar dinheiro.", "code": "ACCOUNT_NOT_OPERABLE", "details": { "status": "CLOSED" } } }, "PROVIDER_NOT_PROVISIONED": { "summary": "PROVIDER_NOT_PROVISIONED", "value": { "message": "Esta conta ainda não terminou de ser aberta.", "code": "PROVIDER_NOT_PROVISIONED" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "REFUND_NOT_PAID": { "summary": "REFUND_NOT_PAID", "value": { "message": "Só é possível estornar um pagamento que foi pago.", "code": "REFUND_NOT_PAID", "details": { "status": "PENDING" } } }, "REFUND_ALREADY_REFUNDED": { "summary": "REFUND_ALREADY_REFUNDED", "value": { "message": "Este pagamento já foi estornado integralmente.", "code": "REFUND_ALREADY_REFUNDED" } }, "REFUND_IN_FLIGHT": { "summary": "REFUND_IN_FLIGHT", "value": { "message": "Já existe um estorno em andamento para este pagamento. Aguarde o desfecho antes de pedir outro.", "code": "REFUND_IN_FLIGHT" } }, "REFUND_INFRACTION_OPEN": { "summary": "REFUND_INFRACTION_OPEN", "value": { "message": "Esta cobrança tem uma contestação MED em andamento; o estorno fica indisponível até o desfecho.", "code": "REFUND_INFRACTION_OPEN", "details": { "protocol": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d" } } }, "REFUND_ABOVE_REMAINING": { "summary": "REFUND_ABOVE_REMAINING", "value": { "message": "O valor do estorno é maior do que o que resta a devolver deste pagamento.", "code": "REFUND_ABOVE_REMAINING", "details": { "remaining": 500 } } }, "REFUND_ABOVE_TICKET_MAX": { "summary": "REFUND_ABOVE_TICKET_MAX", "value": { "message": "O valor do estorno está acima do limite por operação desta conta.", "code": "REFUND_ABOVE_TICKET_MAX", "details": { "max": 1000000 } } }, "REFUND_INSUFFICIENT_BALANCE": { "summary": "REFUND_INSUFFICIENT_BALANCE", "value": { "message": "Saldo insuficiente para estornar este pagamento.", "code": "REFUND_INSUFFICIENT_BALANCE", "details": { "available": 300, "required": 1600 } } }, "ACCOUNT_HELD_BY_STAFF": { "summary": "ACCOUNT_HELD_BY_STAFF", "value": { "message": "Esta conta está retida por decisão do suporte e não pode realizar operações até a liberação.", "code": "ACCOUNT_HELD_BY_STAFF" } }, "ACCOUNT_BLOCKED_BY_PROVIDER": { "summary": "ACCOUNT_BLOCKED_BY_PROVIDER", "value": { "message": "A conta tem um bloqueio na instituição parceira que impede esta operação até o desbloqueio.", "code": "ACCOUNT_BLOCKED_BY_PROVIDER", "details": { "operation": "PIX_OUT" } } }, "PROVIDER_OPERATION_UNAVAILABLE": { "summary": "PROVIDER_OPERATION_UNAVAILABLE", "value": { "message": "Operação indisponível para esta conta no momento.", "code": "PROVIDER_OPERATION_UNAVAILABLE" } } } } } }, "429": { "description": "Limite de requisições excedido.", "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AUTH_TOO_MANY_REQUESTS": { "summary": "AUTH_TOO_MANY_REQUESTS", "value": { "message": "Muitas tentativas. Tente novamente em alguns minutos.", "code": "AUTH_TOO_MANY_REQUESTS", "details": { "retryAfterSeconds": 12 } } } } } } }, "502": { "description": "O banco não respondeu ou recusou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PROVIDER_UNAVAILABLE": { "summary": "PROVIDER_UNAVAILABLE", "value": { "message": "Não houve resposta a tempo. Tente de novo em instantes.", "code": "PROVIDER_UNAVAILABLE", "details": { "status": null, "reason": null } } }, "PROVIDER_REFUSED": { "summary": "PROVIDER_REFUSED", "value": { "message": "Esta operação foi recusada. Confira os dados enviados.", "code": "PROVIDER_REFUSED", "details": { "status": 422, "reason": "Operação recusada pelo banco." } } } } } } }, "503": { "description": "Serviço de consulta ou limitador indisponível; nada foi feito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_UNAVAILABLE": { "summary": "RATE_LIMIT_UNAVAILABLE", "value": { "message": "Proteção de limite indisponível. Tente novamente em instantes.", "code": "RATE_LIMIT_UNAVAILABLE" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/payment/hubp-20261005K7Q2M9XB4T127431/refund' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"amount\": 1000\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/payment/hubp-20261005K7Q2M9XB4T127431/refund';\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: 1000\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.hub.payzu.com.br/api/v1/transactions/payment/hubp-20261005K7Q2M9XB4T127431/refund',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'amount': 1000\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/withdraw": { "post": { "summary": "Sacar para chave Pix", "description": "Escopo: `WITHDRAW`.\n\nEnvia um Pix da conta para uma chave Pix. `amount` é o que chega ao destino; a tarifa é somada por cima. O total sai do saldo disponível na hora do pedido e volta se o saque falhar. A resposta `201` não é dinheiro entregue: a confirmação vem pelo webhook `WITHDRAW_COMPLETED` e a falha por `WITHDRAW_FAILED`. Limite de requisições: 5 por minuto por credencial e 10 por conta, somados com pagamento de Pix copia e cola e estorno.", "operationId": "post_withdraw", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "example": "5f0c1d2e-8a7b-4c3d-9e1f-2a3b4c5d6e7f", "description": "Valor único por operação, de 1 a 255 caracteres ASCII visíveis, sem espaço. Repetir a chave com o mesmo valor e destino devolve a operação original; com outro valor ou destino, `409`. Vale por conta, sem expiração." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWithdraw" }, "example": { "amount": 10000, "pixKey": "fulano@exemplo.com", "pixKeyType": "EMAIL", "comment": "Repasse semanal" } } } }, "responses": { "201": { "description": "Saque registrado. Com a mesma `Idempotency-Key` e os mesmos dados, o saque existente, no estado atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdraw" }, "examples": { "Saque aprovado no banco": { "summary": "Saque aprovado no banco", "value": { "id": "hubp-20261005R4D8TN2WQZ127431", "status": "APPROVED", "amount": 10000, "serviceFee": 250, "totalDebited": 10250, "pixKey": "fulano@exemplo.com", "comment": "Repasse semanal", "e2e": null, "providerRejectedReason": null, "callbackUrl": null, "createdAt": "2026-10-05T14:40:11.002Z", "sentAt": "2026-10-05T14:40:11.380Z", "approvedAt": "2026-10-05T14:40:11.702Z", "confirmedAt": null } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } }, "WITHDRAW_INVALID_IDEMPOTENCY_KEY": { "summary": "WITHDRAW_INVALID_IDEMPOTENCY_KEY", "value": { "message": "O cabeçalho Idempotency-Key deve ter de 1 a 255 caracteres visíveis.", "code": "WITHDRAW_INVALID_IDEMPOTENCY_KEY" } }, "WITHDRAW_INVALID_PIX_KEY": { "summary": "WITHDRAW_INVALID_PIX_KEY", "value": { "message": "A chave PIX é inválida: CPF ou CNPJ com dígito verificador errado, ou 11 dígitos que não são CPF nem celular com DDD.", "code": "WITHDRAW_INVALID_PIX_KEY" } }, "WITHDRAW_PIX_KEY_TYPE_MISMATCH": { "summary": "WITHDRAW_PIX_KEY_TYPE_MISMATCH", "value": { "message": "O tipo informado não corresponde ao formato da chave PIX.", "code": "WITHDRAW_PIX_KEY_TYPE_MISMATCH", "details": { "pixKey": "11987654321", "pixKeyType": "CPF", "inferred": "PHONE" } } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "WITHDRAW_DISABLED": { "summary": "WITHDRAW_DISABLED", "value": { "message": "Saque desabilitado para esta conta.", "code": "WITHDRAW_DISABLED" } }, "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "WITHDRAW" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "409": { "description": "Conflito com o estado atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "WITHDRAW_IDEMPOTENCY_KEY_REUSED": { "summary": "WITHDRAW_IDEMPOTENCY_KEY_REUSED", "value": { "message": "Este Idempotency-Key já foi usado por um saque com outros dados.", "code": "WITHDRAW_IDEMPOTENCY_KEY_REUSED" } } } } } }, "412": { "description": "Falta um passo antes desta operação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CALLBACK_SECRET_MISSING": { "summary": "CALLBACK_SECRET_MISSING", "value": { "message": "Gere o segredo de callback da conta antes de informar uma callbackUrl.", "code": "CALLBACK_SECRET_MISSING" } }, "ACCOUNT_NOT_OPERABLE": { "summary": "ACCOUNT_NOT_OPERABLE", "value": { "message": "Esta conta não está ativa e não pode movimentar dinheiro.", "code": "ACCOUNT_NOT_OPERABLE", "details": { "status": "CLOSED" } } }, "PROVIDER_NOT_PROVISIONED": { "summary": "PROVIDER_NOT_PROVISIONED", "value": { "message": "Esta conta ainda não terminou de ser aberta.", "code": "PROVIDER_NOT_PROVISIONED" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "WITHDRAW_BELOW_TICKET_MIN": { "summary": "WITHDRAW_BELOW_TICKET_MIN", "value": { "message": "O valor é inferior ao mínimo permitido para saque.", "code": "WITHDRAW_BELOW_TICKET_MIN", "details": { "min": 100 } } }, "WITHDRAW_ABOVE_TICKET_MAX": { "summary": "WITHDRAW_ABOVE_TICKET_MAX", "value": { "message": "O valor excede o máximo permitido para saque.", "code": "WITHDRAW_ABOVE_TICKET_MAX", "details": { "max": 1000000 } } }, "WITHDRAW_UNRECOGNIZED_PIX_KEY": { "summary": "WITHDRAW_UNRECOGNIZED_PIX_KEY", "value": { "message": "A chave PIX informada não corresponde a nenhum formato válido.", "code": "WITHDRAW_UNRECOGNIZED_PIX_KEY" } }, "WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE": { "summary": "WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE", "value": { "message": "O saldo desta conta não cobre este saque agora.", "code": "WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE" } }, "WITHDRAW_INSUFFICIENT_BALANCE": { "summary": "WITHDRAW_INSUFFICIENT_BALANCE", "value": { "message": "Saldo insuficiente para este saque.", "code": "WITHDRAW_INSUFFICIENT_BALANCE", "details": { "available": 12500, "required": 20250 } } }, "WITHDRAW_DAILY_LIMIT": { "summary": "WITHDRAW_DAILY_LIMIT", "value": { "message": "O limite diário de saque desta conta foi atingido.", "code": "WITHDRAW_DAILY_LIMIT", "details": { "limit": 1000000, "used": 990000, "required": 20250 } } }, "WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER": { "summary": "WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER", "value": { "message": "A chave PIX de destino foi recusada.", "code": "WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER", "details": { "reason": "Chave Pix não encontrada." } } }, "ACCOUNT_HELD_BY_STAFF": { "summary": "ACCOUNT_HELD_BY_STAFF", "value": { "message": "Esta conta está retida por decisão do suporte e não pode realizar operações até a liberação.", "code": "ACCOUNT_HELD_BY_STAFF" } }, "ACCOUNT_BLOCKED_BY_PROVIDER": { "summary": "ACCOUNT_BLOCKED_BY_PROVIDER", "value": { "message": "A conta tem um bloqueio na instituição parceira que impede esta operação até o desbloqueio.", "code": "ACCOUNT_BLOCKED_BY_PROVIDER", "details": { "operation": "PIX_OUT" } } }, "PROVIDER_OPERATION_UNAVAILABLE": { "summary": "PROVIDER_OPERATION_UNAVAILABLE", "value": { "message": "Operação indisponível para esta conta no momento.", "code": "PROVIDER_OPERATION_UNAVAILABLE" } } } } } }, "429": { "description": "Limite de requisições excedido.", "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AUTH_TOO_MANY_REQUESTS": { "summary": "AUTH_TOO_MANY_REQUESTS", "value": { "message": "Muitas tentativas. Tente novamente em alguns minutos.", "code": "AUTH_TOO_MANY_REQUESTS", "details": { "retryAfterSeconds": 12 } } } } } } }, "502": { "description": "O banco não respondeu ou recusou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PROVIDER_UNAVAILABLE": { "summary": "PROVIDER_UNAVAILABLE", "value": { "message": "Não houve resposta a tempo. Tente de novo em instantes.", "code": "PROVIDER_UNAVAILABLE", "details": { "status": null, "reason": null } } }, "PROVIDER_REFUSED": { "summary": "PROVIDER_REFUSED", "value": { "message": "Esta operação foi recusada. Confira os dados enviados.", "code": "PROVIDER_REFUSED", "details": { "status": 422, "reason": "Operação recusada pelo banco." } } } } } } }, "503": { "description": "Serviço de consulta ou limitador indisponível; nada foi feito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_UNAVAILABLE": { "summary": "RATE_LIMIT_UNAVAILABLE", "value": { "message": "Proteção de limite indisponível. Tente novamente em instantes.", "code": "RATE_LIMIT_UNAVAILABLE" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Uma chave nova para cada operação.\nIDEMPOTENCY_KEY=$(uuidgen)\n\n# Na retentativa, rode de novo só o curl abaixo: ele reaproveita a mesma chave.\ncurl --request POST \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/withdraw' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --header \"Idempotency-Key: $IDEMPOTENCY_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"amount\": 10000,\n \"pixKey\": \"fulano@exemplo.com\",\n \"pixKeyType\": \"EMAIL\",\n \"comment\": \"Repasse semanal\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/withdraw';\n// Uma chave nova por operação; na retentativa, reenvie a mesma chave.\nconst idempotencyKey = crypto.randomUUID();\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Idempotency-Key': idempotencyKey,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n amount: 10000,\n pixKey: 'fulano@exemplo.com',\n pixKeyType: 'EMAIL',\n comment: 'Repasse semanal'\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport uuid\nimport requests\n\n# Uma chave nova por operação; na retentativa, reenvie a mesma chave.\nidempotency_key = str(uuid.uuid4())\n\nresponse = requests.post(\n 'https://api.hub.payzu.com.br/api/v1/transactions/withdraw',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Idempotency-Key': idempotency_key,\n 'Content-Type': 'application/json',\n },\n json={\n 'amount': 10000,\n 'pixKey': 'fulano@exemplo.com',\n 'pixKeyType': 'EMAIL',\n 'comment': 'Repasse semanal'\n },\n)\n\nprint(response.json())" } ] }, "get": { "summary": "Listar saques", "description": "Escopo: `WITHDRAW_READ`.\n\nDevolve os saques da conta, com os pagamentos de Pix copia e cola, do mais recente para o mais antigo, paginados por cursor.", "operationId": "get_withdraws", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Itens por página, de 1 a 100." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" }, "description": "`nextCursor` da página anterior." }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "REQUESTED", "CREATED", "APPROVED", "CONFIRMED", "FAILED" ] }, "description": "Estado do saque." }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string" }, "description": "Início do período, pela data de criação. ISO 8601 ou `AAAA-MM-DD`; data sem hora vale o dia inteiro no horário de Brasília." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string" }, "description": "Fim do período, pela data de criação. ISO 8601 ou `AAAA-MM-DD`; data sem hora vale o dia inteiro no horário de Brasília." } ], "responses": { "200": { "description": "Página de saques.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawList" }, "examples": { "Página de saques": { "summary": "Página de saques", "value": { "data": [ { "id": "hubp-20261005R4D8TN2WQZ127431", "status": "CONFIRMED", "operation": "WITHDRAW", "amount": 10000, "serviceFee": 250, "totalDebited": 10250, "destination": { "pixKey": "f***@exemplo.com", "pixKeyType": "EMAIL" }, "comment": "Repasse semanal", "e2e": "E99999999202610051440f6e5d4c3b2a", "createdAt": "2026-10-05T14:40:11.002Z", "confirmedAt": "2026-10-05T14:40:14.120Z" } ], "nextCursor": "cmu36b0bn000cbngtb7mhzyzw" } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } }, "REQUEST_UNKNOWN_QUERY_PARAM": { "summary": "REQUEST_UNKNOWN_QUERY_PARAM", "value": { "message": "A requisição tem um parâmetro de busca que esta rota não conhece.", "code": "REQUEST_UNKNOWN_QUERY_PARAM", "details": { "unknownParams": [ "page" ], "accepted": [ "cursor", "dateFrom", "dateTo", "limit", "status" ] } } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "WITHDRAW_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/withdraw' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/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.hub.payzu.com.br/api/v1/transactions/withdraw',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/withdraw/{withdrawId}": { "get": { "summary": "Consultar saque", "description": "Escopo: `WITHDRAW_READ`.\n\nDevolve um saque ou um pagamento de Pix copia e cola, com o estado atual. Aceita o `id` do saque e o `withdrawId` dos webhooks.", "operationId": "get_withdraw", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "withdrawId", "required": true, "schema": { "type": "string" }, "example": "hubp-20261005R4D8TN2WQZ127431", "description": "Identificador do saque ou do pagamento de Pix copia e cola." } ], "responses": { "200": { "description": "Saque.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawDetail" }, "examples": { "Saque concluído": { "summary": "Saque concluído", "value": { "id": "hubp-20261005R4D8TN2WQZ127431", "status": "CONFIRMED", "operation": "WITHDRAW", "amount": 10000, "serviceFee": 250, "totalDebited": 10250, "destination": { "pixKey": "f***@exemplo.com", "pixKeyType": "EMAIL" }, "comment": "Repasse semanal", "e2e": "E99999999202610051440f6e5d4c3b2a", "providerRejectedReason": null, "callbackUrl": null, "createdAt": "2026-10-05T14:40:11.002Z", "sentAt": "2026-10-05T14:40:11.380Z", "approvedAt": "2026-10-05T14:40:11.702Z", "confirmedAt": "2026-10-05T14:40:14.120Z", "failedAt": null } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "WITHDRAW_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "WITHDRAW_NOT_FOUND": { "summary": "WITHDRAW_NOT_FOUND", "value": { "message": "Saque não encontrado.", "code": "WITHDRAW_NOT_FOUND" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/withdraw/hubp-20261005R4D8TN2WQZ127431' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/withdraw/hubp-20261005R4D8TN2WQZ127431';\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.hub.payzu.com.br/api/v1/transactions/withdraw/hubp-20261005R4D8TN2WQZ127431',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/withdraw/{withdrawId}/receipt": { "get": { "summary": "Comprovante do saque", "description": "Escopo: `WITHDRAW_READ`.\n\nDevolve o comprovante do saque em PDF, codificado em base64. Só para saque `CONFIRMED`.", "operationId": "get_withdraw_receipt", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "withdrawId", "required": true, "schema": { "type": "string" }, "example": "hubp-20261005R4D8TN2WQZ127431", "description": "Identificador do saque ou do pagamento de Pix copia e cola." } ], "responses": { "200": { "description": "Comprovante.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "examples": { "Comprovante": { "summary": "Comprovante", "value": { "filename": "comprovante-pix-hubp-20261005R4D8TN2WQZ127431.pdf", "contentType": "application/pdf", "fileBase64": "JVBERi0xLjcKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nCvkMlAwUDC1NNUzMjNSMDEz" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "WITHDRAW_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "WITHDRAW_NOT_FOUND": { "summary": "WITHDRAW_NOT_FOUND", "value": { "message": "Saque não encontrado.", "code": "WITHDRAW_NOT_FOUND" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RECEIPT_NOT_SETTLED": { "summary": "RECEIPT_NOT_SETTLED", "value": { "message": "Comprovante disponível só para operação concluída.", "code": "RECEIPT_NOT_SETTLED", "details": { "status": "PENDING" } } }, "RECEIPT_MISSING_END_TO_END": { "summary": "RECEIPT_MISSING_END_TO_END", "value": { "message": "Esta operação ainda não tem end-to-end, e sem ele o comprovante não prova nada. Tente de novo em alguns minutos.", "code": "RECEIPT_MISSING_END_TO_END" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/withdraw/hubp-20261005R4D8TN2WQZ127431/receipt' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/withdraw/hubp-20261005R4D8TN2WQZ127431/receipt';\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.hub.payzu.com.br/api/v1/transactions/withdraw/hubp-20261005R4D8TN2WQZ127431/receipt',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/pix/decode": { "post": { "summary": "Ler Pix copia e cola", "description": "Escopo: `PIX_DICT_READ`.\n\nExtrai os dados de um Pix copia e cola, como chave e valor, sem consultar o banco. Não conta no limite de requisições, não diz quem é o titular e não paga nada. No código dinâmico, `pixKey` vem `null` e só `url` é preenchida.", "operationId": "post_pix_decode", "tags": [ "Pix" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecodeQrCode" }, "example": { "brCode": "00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572" } } } }, "responses": { "200": { "description": "Código lido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecodedQrCode" }, "examples": { "Código estático com valor": { "summary": "Código estático com valor", "value": { "pixKey": "fulano@exemplo.com", "url": null, "amount": 2500, "merchantName": "FULANO DE TAL", "merchantCity": "SAO PAULO", "txid": "PEDIDO4821", "isDynamic": false, "isAmountFixed": true } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } }, "QR_CRC": { "summary": "QR_CRC", "value": { "message": "O código PIX está corrompido — copie novamente do recebedor.", "code": "QR_CRC" } }, "QR_MALFORMED": { "summary": "QR_MALFORMED", "value": { "message": "Este código PIX não está num formato válido.", "code": "QR_MALFORMED" } }, "QR_NOT_PIX": { "summary": "QR_NOT_PIX", "value": { "message": "Este código não é um QR code de PIX.", "code": "QR_NOT_PIX" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "PIX_DICT_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/pix/decode' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"brCode\": \"00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/pix/decode';\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 brCode: '00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572'\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.hub.payzu.com.br/api/v1/transactions/pix/decode',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'brCode': '00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572'\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/pix/destination": { "post": { "summary": "Consultar destinatário", "description": "Escopo: `PIX_DICT_READ`.\n\nMostra o titular e a instituição de uma chave Pix ou de um Pix copia e cola, para conferir antes de pagar. Limite de requisições: 30 consultas por minuto por conta.", "operationId": "post_pix_destination", "tags": [ "Pix" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixDestinationRequest" }, "example": { "pixKey": "52998224725", "pixKeyType": "CPF" } } } }, "responses": { "200": { "description": "Destinatário.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixDestination" }, "examples": { "Destinatário": { "summary": "Destinatário", "value": { "source": "PIX_KEY", "pixKey": "***.982.247-**", "pixKeyType": "CPF", "holder": { "name": "Maria Aparecida Souza", "document": "***.982.247-**" }, "bank": { "name": "Banco Exemplo S.A.", "ispb": "99999999", "branch": "0001", "accountNumber": "****7788" }, "amount": null, "isAmountFixed": false, "isVerified": true } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } }, "WITHDRAW_INVALID_PIX_KEY": { "summary": "WITHDRAW_INVALID_PIX_KEY", "value": { "message": "A chave PIX é inválida: CPF ou CNPJ com dígito verificador errado, ou 11 dígitos que não são CPF nem celular com DDD.", "code": "WITHDRAW_INVALID_PIX_KEY" } }, "WITHDRAW_PIX_KEY_TYPE_MISMATCH": { "summary": "WITHDRAW_PIX_KEY_TYPE_MISMATCH", "value": { "message": "O tipo informado não corresponde ao formato da chave PIX.", "code": "WITHDRAW_PIX_KEY_TYPE_MISMATCH", "details": { "pixKey": "11987654321", "pixKeyType": "CPF", "inferred": "PHONE" } } }, "QR_CRC": { "summary": "QR_CRC", "value": { "message": "O código PIX está corrompido — copie novamente do recebedor.", "code": "QR_CRC" } }, "QR_MALFORMED": { "summary": "QR_MALFORMED", "value": { "message": "Este código PIX não está num formato válido.", "code": "QR_MALFORMED" } }, "QR_NOT_PIX": { "summary": "QR_NOT_PIX", "value": { "message": "Este código não é um QR code de PIX.", "code": "QR_NOT_PIX" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "PIX_DICT_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PIX_DEST_PIX_KEY": { "summary": "PIX_DEST_PIX_KEY", "value": { "message": "Não encontramos essa chave PIX. Confira se ela está correta.", "code": "PIX_DEST_PIX_KEY" } } } } } }, "412": { "description": "Falta um passo antes desta operação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PROVIDER_NOT_PROVISIONED": { "summary": "PROVIDER_NOT_PROVISIONED", "value": { "message": "Esta conta ainda não terminou de ser aberta.", "code": "PROVIDER_NOT_PROVISIONED" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "WITHDRAW_UNRECOGNIZED_PIX_KEY": { "summary": "WITHDRAW_UNRECOGNIZED_PIX_KEY", "value": { "message": "A chave PIX informada não corresponde a nenhum formato válido.", "code": "WITHDRAW_UNRECOGNIZED_PIX_KEY" } }, "PROVIDER_CAPABILITY_NOT_SUPPORTED": { "summary": "PROVIDER_CAPABILITY_NOT_SUPPORTED", "value": { "message": "Esta operação não está disponível para esta conta.", "code": "PROVIDER_CAPABILITY_NOT_SUPPORTED" } }, "PROVIDER_OPERATION_UNAVAILABLE": { "summary": "PROVIDER_OPERATION_UNAVAILABLE", "value": { "message": "Operação indisponível para esta conta no momento.", "code": "PROVIDER_OPERATION_UNAVAILABLE" } } } } } }, "429": { "description": "Limite de requisições excedido.", "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AUTH_TOO_MANY_REQUESTS": { "summary": "AUTH_TOO_MANY_REQUESTS", "value": { "message": "Muitas tentativas. Tente novamente em alguns minutos.", "code": "AUTH_TOO_MANY_REQUESTS", "details": { "retryAfterSeconds": 12 } } } } } } }, "502": { "description": "O banco não respondeu ou recusou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER": { "summary": "PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER", "value": { "message": "A consulta de chaves PIX não está autorizada para esta conta. Fale com o suporte — tentar de novo não resolve.", "code": "PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER" } } } } } }, "503": { "description": "Serviço de consulta ou limitador indisponível; nada foi feito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PIX_DEST_THROTTLED": { "summary": "PIX_DEST_THROTTLED", "value": { "message": "Muitas consultas de chave em pouco tempo. Aguarde um momento e tente de novo.", "code": "PIX_DEST_THROTTLED" } }, "PIX_DEST_UNAVAILABLE": { "summary": "PIX_DEST_UNAVAILABLE", "value": { "message": "A consulta de chaves PIX está indisponível no momento. Tente de novo em instantes.", "code": "PIX_DEST_UNAVAILABLE" } }, "RATE_LIMIT_UNAVAILABLE": { "summary": "RATE_LIMIT_UNAVAILABLE", "value": { "message": "Proteção de limite indisponível. Tente novamente em instantes.", "code": "RATE_LIMIT_UNAVAILABLE" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/pix/destination' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"pixKey\": \"52998224725\",\n \"pixKeyType\": \"CPF\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/pix/destination';\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 pixKey: '52998224725',\n pixKeyType: 'CPF'\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.hub.payzu.com.br/api/v1/transactions/pix/destination',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'pixKey': '52998224725',\n 'pixKeyType': 'CPF'\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/pix/qr-payments": { "post": { "summary": "Pagar Pix copia e cola", "description": "Escopo: `WITHDRAW`.\n\nPaga um Pix copia e cola, estático ou dinâmico, com o saldo disponível da conta. Funciona como um saque: mesma resposta, mesmos limites, teto diário e limite de requisições, com a tarifa de pagamento de Pix copia e cola (`externalPayment` em limites). A `Idempotency-Key` também compara o código pago. Acompanhe pelos webhooks `WITHDRAW_*` e pela consulta de saque, com `operation: EXTERNAL_PAYMENT`.", "operationId": "post_pix_qr_payment", "tags": [ "Pix" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "example": "5f0c1d2e-8a7b-4c3d-9e1f-2a3b4c5d6e7f", "description": "Valor único por operação, de 1 a 255 caracteres ASCII visíveis, sem espaço. Repetir a chave com o mesmo valor e destino devolve a operação original; com outro valor ou destino, `409`. Vale por conta, sem expiração." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayQrCode" }, "example": { "brCode": "00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572", "comment": "Pedido 4821" } } } }, "responses": { "201": { "description": "Pagamento registrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdraw" }, "examples": { "Pagamento aprovado no banco": { "summary": "Pagamento aprovado no banco", "value": { "id": "hubp-20261005H2P6XC8VNM127431", "status": "APPROVED", "amount": 2500, "serviceFee": 100, "totalDebited": 2600, "pixKey": "f***@exemplo.com", "comment": "Pedido 4821", "e2e": null, "providerRejectedReason": null, "callbackUrl": null, "createdAt": "2026-10-05T14:40:11.002Z", "sentAt": "2026-10-05T14:40:11.380Z", "approvedAt": "2026-10-05T14:40:11.702Z", "confirmedAt": null } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } }, "QR_CRC": { "summary": "QR_CRC", "value": { "message": "O código PIX está corrompido — copie novamente do recebedor.", "code": "QR_CRC" } }, "QR_MALFORMED": { "summary": "QR_MALFORMED", "value": { "message": "Este código PIX não está num formato válido.", "code": "QR_MALFORMED" } }, "QR_NOT_PIX": { "summary": "QR_NOT_PIX", "value": { "message": "Este código não é um QR code de PIX.", "code": "QR_NOT_PIX" } }, "WITHDRAW_INVALID_IDEMPOTENCY_KEY": { "summary": "WITHDRAW_INVALID_IDEMPOTENCY_KEY", "value": { "message": "O cabeçalho Idempotency-Key deve ter de 1 a 255 caracteres visíveis.", "code": "WITHDRAW_INVALID_IDEMPOTENCY_KEY" } }, "WITHDRAW_INVALID_PIX_KEY": { "summary": "WITHDRAW_INVALID_PIX_KEY", "value": { "message": "A chave PIX é inválida: CPF ou CNPJ com dígito verificador errado, ou 11 dígitos que não são CPF nem celular com DDD.", "code": "WITHDRAW_INVALID_PIX_KEY" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "WITHDRAW_DISABLED": { "summary": "WITHDRAW_DISABLED", "value": { "message": "Saque desabilitado para esta conta.", "code": "WITHDRAW_DISABLED" } }, "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "WITHDRAW" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PIX_DEST_PIX_KEY": { "summary": "PIX_DEST_PIX_KEY", "value": { "message": "Não encontramos essa chave PIX. Confira se ela está correta.", "code": "PIX_DEST_PIX_KEY" } } } } } }, "409": { "description": "Conflito com o estado atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "WITHDRAW_IDEMPOTENCY_KEY_REUSED": { "summary": "WITHDRAW_IDEMPOTENCY_KEY_REUSED", "value": { "message": "Este Idempotency-Key já foi usado por um saque com outros dados.", "code": "WITHDRAW_IDEMPOTENCY_KEY_REUSED" } } } } } }, "412": { "description": "Falta um passo antes desta operação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CALLBACK_SECRET_MISSING": { "summary": "CALLBACK_SECRET_MISSING", "value": { "message": "Gere o segredo de callback da conta antes de informar uma callbackUrl.", "code": "CALLBACK_SECRET_MISSING" } }, "ACCOUNT_NOT_OPERABLE": { "summary": "ACCOUNT_NOT_OPERABLE", "value": { "message": "Esta conta não está ativa e não pode movimentar dinheiro.", "code": "ACCOUNT_NOT_OPERABLE", "details": { "status": "CLOSED" } } }, "PROVIDER_NOT_PROVISIONED": { "summary": "PROVIDER_NOT_PROVISIONED", "value": { "message": "Esta conta ainda não terminou de ser aberta.", "code": "PROVIDER_NOT_PROVISIONED" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "QR_AMOUNT_MISMATCH": { "summary": "QR_AMOUNT_MISMATCH", "value": { "message": "O valor informado é diferente do valor fixado neste QR code.", "code": "QR_AMOUNT_MISMATCH", "details": { "expected": 2500, "requested": 3000 } } }, "QR_AMOUNT_REQUIRED": { "summary": "QR_AMOUNT_REQUIRED", "value": { "message": "Este QR code não fixa valor — informe quanto pagar.", "code": "QR_AMOUNT_REQUIRED" } }, "QR_AMOUNT_DISAGREES": { "summary": "QR_AMOUNT_DISAGREES", "value": { "message": "O valor impresso no QR code é diferente do que o banco do recebedor informa. Confirme o valor com quem cobrou.", "code": "QR_AMOUNT_DISAGREES" } }, "PROVIDER_CAPABILITY_NOT_SUPPORTED": { "summary": "PROVIDER_CAPABILITY_NOT_SUPPORTED", "value": { "message": "Esta operação não está disponível para esta conta.", "code": "PROVIDER_CAPABILITY_NOT_SUPPORTED" } }, "WITHDRAW_BELOW_TICKET_MIN": { "summary": "WITHDRAW_BELOW_TICKET_MIN", "value": { "message": "O valor é inferior ao mínimo permitido para saque.", "code": "WITHDRAW_BELOW_TICKET_MIN", "details": { "min": 100 } } }, "WITHDRAW_ABOVE_TICKET_MAX": { "summary": "WITHDRAW_ABOVE_TICKET_MAX", "value": { "message": "O valor excede o máximo permitido para saque.", "code": "WITHDRAW_ABOVE_TICKET_MAX", "details": { "max": 1000000 } } }, "WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE": { "summary": "WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE", "value": { "message": "O saldo desta conta não cobre este saque agora.", "code": "WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE" } }, "WITHDRAW_INSUFFICIENT_BALANCE": { "summary": "WITHDRAW_INSUFFICIENT_BALANCE", "value": { "message": "Saldo insuficiente para este saque.", "code": "WITHDRAW_INSUFFICIENT_BALANCE", "details": { "available": 12500, "required": 20250 } } }, "WITHDRAW_DAILY_LIMIT": { "summary": "WITHDRAW_DAILY_LIMIT", "value": { "message": "O limite diário de saque desta conta foi atingido.", "code": "WITHDRAW_DAILY_LIMIT", "details": { "limit": 1000000, "used": 990000, "required": 20250 } } }, "WITHDRAW_UNRECOGNIZED_PIX_KEY": { "summary": "WITHDRAW_UNRECOGNIZED_PIX_KEY", "value": { "message": "A chave PIX informada não corresponde a nenhum formato válido.", "code": "WITHDRAW_UNRECOGNIZED_PIX_KEY" } }, "WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER": { "summary": "WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER", "value": { "message": "A chave PIX de destino foi recusada.", "code": "WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER", "details": { "reason": "Chave Pix não encontrada." } } }, "ACCOUNT_HELD_BY_STAFF": { "summary": "ACCOUNT_HELD_BY_STAFF", "value": { "message": "Esta conta está retida por decisão do suporte e não pode realizar operações até a liberação.", "code": "ACCOUNT_HELD_BY_STAFF" } }, "ACCOUNT_BLOCKED_BY_PROVIDER": { "summary": "ACCOUNT_BLOCKED_BY_PROVIDER", "value": { "message": "A conta tem um bloqueio na instituição parceira que impede esta operação até o desbloqueio.", "code": "ACCOUNT_BLOCKED_BY_PROVIDER", "details": { "operation": "PIX_OUT" } } }, "PROVIDER_OPERATION_UNAVAILABLE": { "summary": "PROVIDER_OPERATION_UNAVAILABLE", "value": { "message": "Operação indisponível para esta conta no momento.", "code": "PROVIDER_OPERATION_UNAVAILABLE" } } } } } }, "429": { "description": "Limite de requisições excedido.", "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AUTH_TOO_MANY_REQUESTS": { "summary": "AUTH_TOO_MANY_REQUESTS", "value": { "message": "Muitas tentativas. Tente novamente em alguns minutos.", "code": "AUTH_TOO_MANY_REQUESTS", "details": { "retryAfterSeconds": 12 } } } } } } }, "502": { "description": "O banco não respondeu ou recusou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER": { "summary": "PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER", "value": { "message": "A consulta de chaves PIX não está autorizada para esta conta. Fale com o suporte — tentar de novo não resolve.", "code": "PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER" } }, "PROVIDER_UNAVAILABLE": { "summary": "PROVIDER_UNAVAILABLE", "value": { "message": "Não houve resposta a tempo. Tente de novo em instantes.", "code": "PROVIDER_UNAVAILABLE", "details": { "status": null, "reason": null } } }, "PROVIDER_REFUSED": { "summary": "PROVIDER_REFUSED", "value": { "message": "Esta operação foi recusada. Confira os dados enviados.", "code": "PROVIDER_REFUSED", "details": { "status": 422, "reason": "Operação recusada pelo banco." } } } } } } }, "503": { "description": "Serviço de consulta ou limitador indisponível; nada foi feito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PIX_DEST_UNAVAILABLE": { "summary": "PIX_DEST_UNAVAILABLE", "value": { "message": "A consulta de chaves PIX está indisponível no momento. Tente de novo em instantes.", "code": "PIX_DEST_UNAVAILABLE" } }, "PIX_DEST_THROTTLED": { "summary": "PIX_DEST_THROTTLED", "value": { "message": "Muitas consultas de chave em pouco tempo. Aguarde um momento e tente de novo.", "code": "PIX_DEST_THROTTLED" } }, "RATE_LIMIT_UNAVAILABLE": { "summary": "RATE_LIMIT_UNAVAILABLE", "value": { "message": "Proteção de limite indisponível. Tente novamente em instantes.", "code": "RATE_LIMIT_UNAVAILABLE" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Uma chave nova para cada operação.\nIDEMPOTENCY_KEY=$(uuidgen)\n\n# Na retentativa, rode de novo só o curl abaixo: ele reaproveita a mesma chave.\ncurl --request POST \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/pix/qr-payments' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --header \"Idempotency-Key: $IDEMPOTENCY_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"brCode\": \"00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572\",\n \"comment\": \"Pedido 4821\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/pix/qr-payments';\n// Uma chave nova por operação; na retentativa, reenvie a mesma chave.\nconst idempotencyKey = crypto.randomUUID();\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Idempotency-Key': idempotencyKey,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n brCode: '00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572',\n comment: 'Pedido 4821'\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport uuid\nimport requests\n\n# Uma chave nova por operação; na retentativa, reenvie a mesma chave.\nidempotency_key = str(uuid.uuid4())\n\nresponse = requests.post(\n 'https://api.hub.payzu.com.br/api/v1/transactions/pix/qr-payments',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Idempotency-Key': idempotency_key,\n 'Content-Type': 'application/json',\n },\n json={\n 'brCode': '00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572',\n 'comment': 'Pedido 4821'\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/pix-keys": { "get": { "summary": "Listar chaves Pix", "description": "Escopo: `PIX_KEY_READ`.\n\nDevolve as chaves Pix da conta, com a padrão em primeiro lugar. As outras vêm da mais antiga para a mais nova.", "operationId": "get_pix_keys", "tags": [ "Pix Keys" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Chaves da conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixKeyList" }, "examples": { "Chaves da conta": { "summary": "Chaves da conta", "value": [ { "id": "cmu5k2x0a000301s6ab12cd34", "key": "b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03", "type": "EVP", "status": "ACTIVE", "isDefault": true, "createdAt": "2026-09-17T14:32:05.123Z", "updatedAt": "2026-09-17T14:32:05.123Z" }, { "id": "cmu5k2x0a000401s6ef56gh78", "key": "12345678000195", "type": "CNPJ", "status": "ACTIVE", "isDefault": false, "createdAt": "2026-09-20T10:00:00.000Z", "updatedAt": "2026-09-20T10:00:00.000Z" } ] } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "PIX_KEY_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/pix-keys' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/pix-keys';\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.hub.payzu.com.br/api/v1/transactions/pix-keys',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] }, "post": { "summary": "Criar chave Pix", "description": "Escopo: `PIX_KEY_WRITE`.\n\nRegistra na conta uma chave Pix nova, aleatória (`EVP`) ou CNPJ. A chave já volta `ACTIVE`, e a primeira chave da conta vira a padrão.", "operationId": "post_pix_key", "tags": [ "Pix Keys" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePixKey" }, "example": { "type": "EVP" } } } }, "responses": { "201": { "description": "Chave criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixKey" }, "examples": { "Chave": { "summary": "Chave", "value": { "id": "cmu5k2x0a000301s6ab12cd34", "key": "b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03", "type": "EVP", "status": "ACTIVE", "isDefault": true, "createdAt": "2026-09-17T14:32:05.123Z", "updatedAt": "2026-09-17T14:32:05.123Z" } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } }, "PIX_KEY_REQUIRED": { "summary": "PIX_KEY_REQUIRED", "value": { "message": "Chave é obrigatória para tipos diferentes de EVP.", "code": "PIX_KEY_REQUIRED" } }, "PIX_KEY_RANDOM_KEY_NOT_ALLOWED": { "summary": "PIX_KEY_RANDOM_KEY_NOT_ALLOWED", "value": { "message": "Chave aleatória é gerada automaticamente e não pode ser informada.", "code": "PIX_KEY_RANDOM_KEY_NOT_ALLOWED" } }, "PIX_KEY_DOCUMENT_NOT_HOLDER": { "summary": "PIX_KEY_DOCUMENT_NOT_HOLDER", "value": { "message": "A chave de CPF ou CNPJ precisa ser o documento do titular da conta.", "code": "PIX_KEY_DOCUMENT_NOT_HOLDER" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "PIX_KEY_WRITE" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "409": { "description": "Conflito com o estado atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PIX_KEY_DUPLICATED": { "summary": "PIX_KEY_DUPLICATED", "value": { "message": "Esta chave já está cadastrada na conta.", "code": "PIX_KEY_DUPLICATED" } } } } } }, "412": { "description": "Falta um passo antes desta operação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PROVIDER_NOT_PROVISIONED": { "summary": "PROVIDER_NOT_PROVISIONED", "value": { "message": "Esta conta ainda não terminou de ser aberta.", "code": "PROVIDER_NOT_PROVISIONED" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PIX_KEY_TYPE_NOT_SUPPORTED_BY_PROVIDER": { "summary": "PIX_KEY_TYPE_NOT_SUPPORTED_BY_PROVIDER", "value": { "message": "Não é possível criar chave PIX deste tipo nesta conta.", "code": "PIX_KEY_TYPE_NOT_SUPPORTED_BY_PROVIDER" } }, "PIX_KEY_PROVIDER_REFUSED": { "summary": "PIX_KEY_PROVIDER_REFUSED", "value": { "message": "A chave PIX foi recusada.", "code": "PIX_KEY_PROVIDER_REFUSED", "details": { "reason": "Chave já registrada em outra instituição." } } }, "PROVIDER_OPERATION_UNAVAILABLE": { "summary": "PROVIDER_OPERATION_UNAVAILABLE", "value": { "message": "Operação indisponível para esta conta no momento.", "code": "PROVIDER_OPERATION_UNAVAILABLE" } }, "PROVIDER_CAPABILITY_NOT_SUPPORTED": { "summary": "PROVIDER_CAPABILITY_NOT_SUPPORTED", "value": { "message": "Esta operação não está disponível para esta conta.", "code": "PROVIDER_CAPABILITY_NOT_SUPPORTED" } }, "ACCOUNT_HELD_BY_STAFF": { "summary": "ACCOUNT_HELD_BY_STAFF", "value": { "message": "Esta conta está retida por decisão do suporte e não pode realizar operações até a liberação.", "code": "ACCOUNT_HELD_BY_STAFF" } } } } } }, "502": { "description": "O banco não respondeu ou recusou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PROVIDER_UNAVAILABLE": { "summary": "PROVIDER_UNAVAILABLE", "value": { "message": "Não houve resposta a tempo. Tente de novo em instantes.", "code": "PROVIDER_UNAVAILABLE", "details": { "status": null, "reason": null } } }, "PROVIDER_REFUSED": { "summary": "PROVIDER_REFUSED", "value": { "message": "Esta operação foi recusada. Confira os dados enviados.", "code": "PROVIDER_REFUSED", "details": { "status": 422, "reason": "Operação recusada pelo banco." } } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/pix-keys' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"type\": \"EVP\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/pix-keys';\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 type: 'EVP'\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.hub.payzu.com.br/api/v1/transactions/pix-keys',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'type': 'EVP'\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/pix-keys/{pixKeyId}/default": { "put": { "summary": "Definir chave padrão", "description": "Escopo: `PIX_KEY_WRITE`.\n\nTroca a chave padrão da conta pela chave indicada. A chave padrão é a que recebe cobrança e a que identifica a sua conta nas transferências que você envia. Para receber transferência, vale qualquer chave `ACTIVE`. Só chave `ACTIVE` pode virar padrão.", "operationId": "put_pix_key_default", "tags": [ "Pix Keys" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "pixKeyId", "required": true, "schema": { "type": "string" }, "example": "cmu5k2x0a000301s6ab12cd34", "description": "Identificador da chave (`id`), não o valor dela." } ], "responses": { "200": { "description": "A chave, agora padrão.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixKey" }, "examples": { "Chave": { "summary": "Chave", "value": { "id": "cmu5k2x0a000301s6ab12cd34", "key": "b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03", "type": "EVP", "status": "ACTIVE", "isDefault": true, "createdAt": "2026-09-17T14:32:05.123Z", "updatedAt": "2026-09-17T14:32:05.123Z" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "PIX_KEY_WRITE" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PIX_KEY_NOT_FOUND": { "summary": "PIX_KEY_NOT_FOUND", "value": { "message": "Chave PIX não encontrada.", "code": "PIX_KEY_NOT_FOUND" } } } } } }, "412": { "description": "Falta um passo antes desta operação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PROVIDER_NOT_PROVISIONED": { "summary": "PROVIDER_NOT_PROVISIONED", "value": { "message": "Esta conta ainda não terminou de ser aberta.", "code": "PROVIDER_NOT_PROVISIONED" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PIX_KEY_ONLY_ACTIVE_CAN_BE_DEFAULT": { "summary": "PIX_KEY_ONLY_ACTIVE_CAN_BE_DEFAULT", "value": { "message": "Apenas chave ativa pode ser definida como padrão.", "code": "PIX_KEY_ONLY_ACTIVE_CAN_BE_DEFAULT" } }, "PIX_KEY_PROVIDER_REFUSED": { "summary": "PIX_KEY_PROVIDER_REFUSED", "value": { "message": "A chave PIX foi recusada.", "code": "PIX_KEY_PROVIDER_REFUSED", "details": { "reason": "Chave já registrada em outra instituição." } } }, "PROVIDER_OPERATION_UNAVAILABLE": { "summary": "PROVIDER_OPERATION_UNAVAILABLE", "value": { "message": "Operação indisponível para esta conta no momento.", "code": "PROVIDER_OPERATION_UNAVAILABLE" } }, "PROVIDER_CAPABILITY_NOT_SUPPORTED": { "summary": "PROVIDER_CAPABILITY_NOT_SUPPORTED", "value": { "message": "Esta operação não está disponível para esta conta.", "code": "PROVIDER_CAPABILITY_NOT_SUPPORTED" } }, "ACCOUNT_HELD_BY_STAFF": { "summary": "ACCOUNT_HELD_BY_STAFF", "value": { "message": "Esta conta está retida por decisão do suporte e não pode realizar operações até a liberação.", "code": "ACCOUNT_HELD_BY_STAFF" } } } } } }, "502": { "description": "O banco não respondeu ou recusou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PROVIDER_UNAVAILABLE": { "summary": "PROVIDER_UNAVAILABLE", "value": { "message": "Não houve resposta a tempo. Tente de novo em instantes.", "code": "PROVIDER_UNAVAILABLE", "details": { "status": null, "reason": null } } }, "PROVIDER_REFUSED": { "summary": "PROVIDER_REFUSED", "value": { "message": "Esta operação foi recusada. Confira os dados enviados.", "code": "PROVIDER_REFUSED", "details": { "status": 422, "reason": "Operação recusada pelo banco." } } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request PUT \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/pix-keys/cmu5k2x0a000301s6ab12cd34/default' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/pix-keys/cmu5k2x0a000301s6ab12cd34/default';\n\nconst response = await fetch(url, {\n method: 'PUT',\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.put(\n 'https://api.hub.payzu.com.br/api/v1/transactions/pix-keys/cmu5k2x0a000301s6ab12cd34/default',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/pix-keys/{pixKeyId}": { "delete": { "summary": "Apagar chave Pix", "description": "Escopo: `PIX_KEY_WRITE`.\n\nRemove a chave da conta e do DICT. A chave padrão não pode ser apagada, e uma chave já apagada responde `404`.", "operationId": "delete_pix_key", "tags": [ "Pix Keys" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "pixKeyId", "required": true, "schema": { "type": "string" }, "example": "cmu5k2x0a000301s6ab12cd34", "description": "Identificador da chave (`id`), não o valor dela." } ], "responses": { "204": { "description": "Sem corpo." }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "PIX_KEY_WRITE" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PIX_KEY_NOT_FOUND": { "summary": "PIX_KEY_NOT_FOUND", "value": { "message": "Chave PIX não encontrada.", "code": "PIX_KEY_NOT_FOUND" } } } } } }, "412": { "description": "Falta um passo antes desta operação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PROVIDER_NOT_PROVISIONED": { "summary": "PROVIDER_NOT_PROVISIONED", "value": { "message": "Esta conta ainda não terminou de ser aberta.", "code": "PROVIDER_NOT_PROVISIONED" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PIX_KEY_DEFAULT_CANNOT_BE_REMOVED": { "summary": "PIX_KEY_DEFAULT_CANNOT_BE_REMOVED", "value": { "message": "A chave padrão não pode ser removida. Defina outra como padrão antes.", "code": "PIX_KEY_DEFAULT_CANNOT_BE_REMOVED" } }, "PIX_KEY_DEFAULT_ON_PROVIDER": { "summary": "PIX_KEY_DEFAULT_ON_PROVIDER", "value": { "message": "Esta chave é a padrão da conta. Defina outra chave como padrão antes de removê-la.", "code": "PIX_KEY_DEFAULT_ON_PROVIDER" } }, "PIX_KEY_PROVIDER_REFUSED": { "summary": "PIX_KEY_PROVIDER_REFUSED", "value": { "message": "A chave PIX foi recusada.", "code": "PIX_KEY_PROVIDER_REFUSED", "details": { "reason": "Chave já registrada em outra instituição." } } }, "PROVIDER_OPERATION_UNAVAILABLE": { "summary": "PROVIDER_OPERATION_UNAVAILABLE", "value": { "message": "Operação indisponível para esta conta no momento.", "code": "PROVIDER_OPERATION_UNAVAILABLE" } }, "PROVIDER_CAPABILITY_NOT_SUPPORTED": { "summary": "PROVIDER_CAPABILITY_NOT_SUPPORTED", "value": { "message": "Esta operação não está disponível para esta conta.", "code": "PROVIDER_CAPABILITY_NOT_SUPPORTED" } }, "ACCOUNT_HELD_BY_STAFF": { "summary": "ACCOUNT_HELD_BY_STAFF", "value": { "message": "Esta conta está retida por decisão do suporte e não pode realizar operações até a liberação.", "code": "ACCOUNT_HELD_BY_STAFF" } } } } } }, "502": { "description": "O banco não respondeu ou recusou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PROVIDER_UNAVAILABLE": { "summary": "PROVIDER_UNAVAILABLE", "value": { "message": "Não houve resposta a tempo. Tente de novo em instantes.", "code": "PROVIDER_UNAVAILABLE", "details": { "status": null, "reason": null } } }, "PROVIDER_REFUSED": { "summary": "PROVIDER_REFUSED", "value": { "message": "Esta operação foi recusada. Confira os dados enviados.", "code": "PROVIDER_REFUSED", "details": { "status": 422, "reason": "Operação recusada pelo banco." } } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request DELETE \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/pix-keys/cmu5k2x0a000301s6ab12cd34' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/pix-keys/cmu5k2x0a000301s6ab12cd34';\n\nconst response = await fetch(url, {\n method: 'DELETE',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconsole.log(response.status);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.delete(\n 'https://api.hub.payzu.com.br/api/v1/transactions/pix-keys/cmu5k2x0a000301s6ab12cd34',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.status_code)" } ] } }, "/transactions/internal-transfer": { "post": { "summary": "Transferir para outra conta PayZu", "description": "Escopo: `INTERNAL_TRANSFER`.\n\nEnvia dinheiro da sua conta para outra conta PayZu, identificada pela chave Pix dela. O valor não passa pelo Pix, e a resposta já traz o resultado: `CONFIRMED` é dinheiro entregue. A tarifa é somada por cima. Num `502` em que o banco não respondeu ou recusou temporariamente, a transferência fica `REQUESTED` e só a mesma `Idempotency-Key` devolve a original; recusa definitiva deixa a transferência `FAILED`. Limite de requisições: 5 por minuto por credencial e 10 por conta.", "operationId": "post_internal_transfer", "tags": [ "Internal Transfers" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "example": "5f0c1d2e-8a7b-4c3d-9e1f-2a3b4c5d6e7f", "description": "Valor único por operação, de 1 a 255 caracteres ASCII visíveis, sem espaço. Repetir a chave com o mesmo valor e destino devolve a operação original; com outro valor ou destino, `409`. Vale por conta, sem expiração." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInternalTransfer" }, "example": { "amount": 10000, "toPixKey": "financeiro@lojaparceira.com.br", "comment": "Repasse do mês" } } } }, "responses": { "201": { "description": "Transferência registrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalTransfer" }, "examples": { "Transferência concluída": { "summary": "Transferência concluída", "value": { "id": "hubp-20261005L9C3VH6KMA127431", "status": "CONFIRMED", "side": "SENT", "amount": 10000, "serviceFee": 100, "totalDebited": 10100, "counterparty": { "name": "Loja Parceira Ltda", "document": "12.345.678/0001-95", "pixKey": "financeiro@lojaparceira.com.br" }, "comment": "Repasse do mês", "providerRejectedReason": null, "callbackUrl": null, "createdAt": "2026-10-05T15:02:44.010Z", "confirmedAt": "2026-10-05T15:02:44.418Z", "failedAt": null } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } }, "TRANSFER_INVALID_IDEMPOTENCY_KEY": { "summary": "TRANSFER_INVALID_IDEMPOTENCY_KEY", "value": { "message": "O cabeçalho Idempotency-Key deve ter de 1 a 255 caracteres visíveis.", "code": "TRANSFER_INVALID_IDEMPOTENCY_KEY" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TRANSFER_DISABLED": { "summary": "TRANSFER_DISABLED", "value": { "message": "Transferência entre contas desabilitada para esta conta.", "code": "TRANSFER_DISABLED" } }, "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "INTERNAL_TRANSFER" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TRANSFER_DESTINATION": { "summary": "TRANSFER_DESTINATION", "value": { "message": "Nenhuma conta do hub tem esta chave PIX ativa.", "code": "TRANSFER_DESTINATION" } } } } } }, "409": { "description": "Conflito com o estado atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TRANSFER_IDEMPOTENCY_KEY_REUSED": { "summary": "TRANSFER_IDEMPOTENCY_KEY_REUSED", "value": { "message": "Esta chave de idempotência já foi usada para outra transferência.", "code": "TRANSFER_IDEMPOTENCY_KEY_REUSED" } } } } } }, "412": { "description": "Falta um passo antes desta operação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CALLBACK_SECRET_MISSING": { "summary": "CALLBACK_SECRET_MISSING", "value": { "message": "Gere o segredo de callback da conta antes de informar uma callbackUrl.", "code": "CALLBACK_SECRET_MISSING" } }, "ACCOUNT_NOT_OPERABLE": { "summary": "ACCOUNT_NOT_OPERABLE", "value": { "message": "Esta conta não está ativa e não pode movimentar dinheiro.", "code": "ACCOUNT_NOT_OPERABLE", "details": { "status": "CLOSED" } } }, "PROVIDER_NOT_PROVISIONED": { "summary": "PROVIDER_NOT_PROVISIONED", "value": { "message": "Esta conta ainda não terminou de ser aberta.", "code": "PROVIDER_NOT_PROVISIONED" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ACCOUNT_BLOCKED_BY_PROVIDER": { "summary": "ACCOUNT_BLOCKED_BY_PROVIDER", "value": { "message": "A conta tem um bloqueio na instituição parceira que impede esta operação até o desbloqueio.", "code": "ACCOUNT_BLOCKED_BY_PROVIDER", "details": { "operation": "INTERNAL_TRANSFER_OUT" } } }, "TRANSFER_NOT_SUPPORTED": { "summary": "TRANSFER_NOT_SUPPORTED", "value": { "message": "Esta conta não faz transferência entre contas.", "code": "TRANSFER_NOT_SUPPORTED" } }, "TRANSFER_BELOW_TICKET_MIN": { "summary": "TRANSFER_BELOW_TICKET_MIN", "value": { "message": "O valor é inferior ao mínimo permitido para transferência entre contas.", "code": "TRANSFER_BELOW_TICKET_MIN", "details": { "min": 100 } } }, "TRANSFER_ABOVE_TICKET_MAX": { "summary": "TRANSFER_ABOVE_TICKET_MAX", "value": { "message": "O valor excede o máximo permitido para transferência entre contas.", "code": "TRANSFER_ABOVE_TICKET_MAX", "details": { "max": 1000000 } } }, "TRANSFER_SAME_ACCOUNT": { "summary": "TRANSFER_SAME_ACCOUNT", "value": { "message": "A conta de destino é a própria conta de origem.", "code": "TRANSFER_SAME_ACCOUNT" } }, "TRANSFER_AMBIGUOUS_DESTINATION": { "summary": "TRANSFER_AMBIGUOUS_DESTINATION", "value": { "message": "Esta chave PIX está ativa em mais de uma conta; não dá para decidir o destino.", "code": "TRANSFER_AMBIGUOUS_DESTINATION" } }, "TRANSFER_DESTINATION_NOT_ACTIVE": { "summary": "TRANSFER_DESTINATION_NOT_ACTIVE", "value": { "message": "A conta de destino não está ativa.", "code": "TRANSFER_DESTINATION_NOT_ACTIVE", "details": { "status": "SUSPENDED" } } }, "TRANSFER_DIFFERENT_PROVIDER": { "summary": "TRANSFER_DIFFERENT_PROVIDER", "value": { "message": "A conta de destino está em outra instituição; use um PIX.", "code": "TRANSFER_DIFFERENT_PROVIDER" } }, "TRANSFER_MAIN_ACCOUNT_DESTINATION": { "summary": "TRANSFER_MAIN_ACCOUNT_DESTINATION", "value": { "message": "A conta principal da PayZu não recebe transferência entre contas; para pagar a PayZu, use uma cobrança.", "code": "TRANSFER_MAIN_ACCOUNT_DESTINATION" } }, "TRANSFER_NO_ORIGIN_KEY": { "summary": "TRANSFER_NO_ORIGIN_KEY", "value": { "message": "Esta conta não tem chave PIX ativa para enviar a transferência.", "code": "TRANSFER_NO_ORIGIN_KEY" } }, "TRANSFER_INSUFFICIENT_BALANCE": { "summary": "TRANSFER_INSUFFICIENT_BALANCE", "value": { "message": "Saldo insuficiente para esta transferência.", "code": "TRANSFER_INSUFFICIENT_BALANCE", "details": { "available": 5000, "required": 10050 } } }, "TRANSFER_DAILY_LIMIT": { "summary": "TRANSFER_DAILY_LIMIT", "value": { "message": "O limite diário de transferência desta conta foi atingido.", "code": "TRANSFER_DAILY_LIMIT", "details": { "limit": 1000000, "used": 995000, "required": 10050 } } }, "PROVIDER_OPERATION_UNAVAILABLE": { "summary": "PROVIDER_OPERATION_UNAVAILABLE", "value": { "message": "Operação indisponível para esta conta no momento.", "code": "PROVIDER_OPERATION_UNAVAILABLE" } }, "ACCOUNT_HELD_BY_STAFF": { "summary": "ACCOUNT_HELD_BY_STAFF", "value": { "message": "Esta conta está retida por decisão do suporte e não pode realizar operações até a liberação.", "code": "ACCOUNT_HELD_BY_STAFF" } } } } } }, "429": { "description": "Limite de requisições excedido.", "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AUTH_TOO_MANY_REQUESTS": { "summary": "AUTH_TOO_MANY_REQUESTS", "value": { "message": "Muitas tentativas. Tente novamente em alguns minutos.", "code": "AUTH_TOO_MANY_REQUESTS", "details": { "retryAfterSeconds": 12 } } } } } } }, "502": { "description": "O banco não respondeu ou recusou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PROVIDER_UNAVAILABLE": { "summary": "PROVIDER_UNAVAILABLE", "value": { "message": "Não houve resposta a tempo. Tente de novo em instantes.", "code": "PROVIDER_UNAVAILABLE", "details": { "status": null, "reason": null } } }, "PROVIDER_REFUSED": { "summary": "PROVIDER_REFUSED", "value": { "message": "Esta operação foi recusada. Confira os dados enviados.", "code": "PROVIDER_REFUSED", "details": { "status": 422, "reason": "Operação recusada pelo banco." } } } } } } }, "503": { "description": "Serviço de consulta ou limitador indisponível; nada foi feito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_UNAVAILABLE": { "summary": "RATE_LIMIT_UNAVAILABLE", "value": { "message": "Proteção de limite indisponível. Tente novamente em instantes.", "code": "RATE_LIMIT_UNAVAILABLE" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Uma chave nova para cada operação.\nIDEMPOTENCY_KEY=$(uuidgen)\n\n# Na retentativa, rode de novo só o curl abaixo: ele reaproveita a mesma chave.\ncurl --request POST \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/internal-transfer' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --header \"Idempotency-Key: $IDEMPOTENCY_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"amount\": 10000,\n \"toPixKey\": \"financeiro@lojaparceira.com.br\",\n \"comment\": \"Repasse do mês\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/internal-transfer';\n// Uma chave nova por operação; na retentativa, reenvie a mesma chave.\nconst idempotencyKey = crypto.randomUUID();\n\nconst response = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Idempotency-Key': idempotencyKey,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n amount: 10000,\n toPixKey: 'financeiro@lojaparceira.com.br',\n comment: 'Repasse do mês'\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport uuid\nimport requests\n\n# Uma chave nova por operação; na retentativa, reenvie a mesma chave.\nidempotency_key = str(uuid.uuid4())\n\nresponse = requests.post(\n 'https://api.hub.payzu.com.br/api/v1/transactions/internal-transfer',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Idempotency-Key': idempotency_key,\n 'Content-Type': 'application/json',\n },\n json={\n 'amount': 10000,\n 'toPixKey': 'financeiro@lojaparceira.com.br',\n 'comment': 'Repasse do mês'\n },\n)\n\nprint(response.json())" } ] }, "get": { "summary": "Listar transferências", "description": "Escopo: `INTERNAL_TRANSFER_READ`.\n\nDevolve as transferências que a conta enviou e recebeu, da mais recente para a mais antiga, paginadas por cursor.", "operationId": "get_internal_transfers", "tags": [ "Internal Transfers" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Itens por página, de 1 a 100." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" }, "description": "`nextCursor` da página anterior." }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "REQUESTED", "CONFIRMED", "FAILED" ] }, "description": "Estado da transferência." }, { "in": "query", "name": "side", "required": false, "schema": { "type": "string", "enum": [ "SENT", "RECEIVED" ] }, "description": "Só um lado: `SENT` ou `RECEIVED`. Sem ele, vêm os dois." }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string" }, "description": "Início do período, pela data de criação. ISO 8601 ou `AAAA-MM-DD`; data sem hora vale o dia inteiro no horário de Brasília." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string" }, "description": "Fim do período, pela data de criação. ISO 8601 ou `AAAA-MM-DD`; data sem hora vale o dia inteiro no horário de Brasília." } ], "responses": { "200": { "description": "Página de transferências.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalTransferList" }, "examples": { "Página de transferências": { "summary": "Página de transferências", "value": { "data": [ { "id": "hubp-20261005L9C3VH6KMA127431", "status": "CONFIRMED", "side": "SENT", "amount": 10000, "serviceFee": 100, "totalDebited": 10100, "counterparty": { "name": "Loja Parceira Ltda", "document": "12.345.678/0001-95", "pixKey": "f***@lojaparceira.com.br" }, "comment": "Repasse do mês", "providerRejectedReason": null, "callbackUrl": null, "createdAt": "2026-10-05T15:02:44.010Z", "confirmedAt": "2026-10-05T15:02:44.418Z", "failedAt": null }, { "id": "hubp-20261004M3N7KP2QRS998812", "status": "CONFIRMED", "side": "RECEIVED", "amount": 5000, "serviceFee": 0, "totalDebited": 0, "counterparty": { "name": "Loja Parceira Ltda", "document": "12.345.678/0001-95", "pixKey": "f***@lojaparceira.com.br" }, "comment": null, "providerRejectedReason": null, "callbackUrl": null, "createdAt": "2026-10-04T11:20:00.000Z", "confirmedAt": "2026-10-04T11:20:00.390Z", "failedAt": null } ], "nextCursor": "cmu39c1do000dbngt8nk2abcd" } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } }, "REQUEST_UNKNOWN_QUERY_PARAM": { "summary": "REQUEST_UNKNOWN_QUERY_PARAM", "value": { "message": "A requisição tem um parâmetro de busca que esta rota não conhece.", "code": "REQUEST_UNKNOWN_QUERY_PARAM", "details": { "unknownParams": [ "page" ], "accepted": [ "cursor", "dateFrom", "dateTo", "limit", "side", "status" ] } } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "INTERNAL_TRANSFER_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/internal-transfer' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/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.hub.payzu.com.br/api/v1/transactions/internal-transfer',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/internal-transfer/{transferId}": { "get": { "summary": "Consultar transferência", "description": "Escopo: `INTERNAL_TRANSFER_READ`.\n\nDevolve uma transferência que a conta enviou ou recebeu. Aceita o `id` da transferência e o `transferId` dos webhooks.", "operationId": "get_internal_transfer", "tags": [ "Internal Transfers" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "transferId", "required": true, "schema": { "type": "string" }, "example": "hubp-20261005L9C3VH6KMA127431", "description": "Identificador da transferência." } ], "responses": { "200": { "description": "Transferência.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalTransfer" }, "examples": { "Transferência concluída": { "summary": "Transferência concluída", "value": { "id": "hubp-20261005L9C3VH6KMA127431", "status": "CONFIRMED", "side": "SENT", "amount": 10000, "serviceFee": 100, "totalDebited": 10100, "counterparty": { "name": "Loja Parceira Ltda", "document": "12.345.678/0001-95", "pixKey": "f***@lojaparceira.com.br" }, "comment": "Repasse do mês", "providerRejectedReason": null, "callbackUrl": null, "createdAt": "2026-10-05T15:02:44.010Z", "confirmedAt": "2026-10-05T15:02:44.418Z", "failedAt": null } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "INTERNAL_TRANSFER_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TRANSFER_NOT_FOUND": { "summary": "TRANSFER_NOT_FOUND", "value": { "message": "Transferência não encontrada.", "code": "TRANSFER_NOT_FOUND" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/internal-transfer/hubp-20261005L9C3VH6KMA127431' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/internal-transfer/hubp-20261005L9C3VH6KMA127431';\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.hub.payzu.com.br/api/v1/transactions/internal-transfer/hubp-20261005L9C3VH6KMA127431',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/internal-transfer/{transferId}/receipt": { "get": { "summary": "Comprovante da transferência", "description": "Escopo: `INTERNAL_TRANSFER_READ`.\n\nDevolve o comprovante da transferência em PDF, codificado em base64. Só para transferência `CONFIRMED`. Não é comprovante de Pix e não tem end-to-end.", "operationId": "get_internal_transfer_receipt", "tags": [ "Internal Transfers" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "transferId", "required": true, "schema": { "type": "string" }, "example": "hubp-20261005L9C3VH6KMA127431", "description": "Identificador da transferência." } ], "responses": { "200": { "description": "Comprovante.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "examples": { "Comprovante": { "summary": "Comprovante", "value": { "filename": "comprovante-transferencia-hubp-20261005L9C3VH6KMA127431.pdf", "contentType": "application/pdf", "fileBase64": "JVBERi0xLjcKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nCvkMlAwUDC1NNUzMjNSMDEz" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "INTERNAL_TRANSFER_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TRANSFER_NOT_FOUND": { "summary": "TRANSFER_NOT_FOUND", "value": { "message": "Transferência não encontrada.", "code": "TRANSFER_NOT_FOUND" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RECEIPT_NOT_SETTLED": { "summary": "RECEIPT_NOT_SETTLED", "value": { "message": "Comprovante disponível só para operação concluída.", "code": "RECEIPT_NOT_SETTLED", "details": { "status": "PENDING" } } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/internal-transfer/hubp-20261005L9C3VH6KMA127431/receipt' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/internal-transfer/hubp-20261005L9C3VH6KMA127431/receipt';\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.hub.payzu.com.br/api/v1/transactions/internal-transfer/hubp-20261005L9C3VH6KMA127431/receipt',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/deposit/{depositId}": { "get": { "summary": "Consultar depósito", "description": "Escopo: `DEPOSIT_READ`.\n\nDevolve um depósito, que é um Pix recebido numa chave da conta sem cobrança. Use o `depositId` do webhook `DEPOSIT_RECEIVED`.", "operationId": "get_deposit", "tags": [ "Deposits" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "depositId", "required": true, "schema": { "type": "string" }, "example": "cmu4a1b2c000001s6xyz98765", "description": "Identificador do depósito." } ], "responses": { "200": { "description": "Depósito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deposit" }, "examples": { "Depósito": { "summary": "Depósito", "value": { "id": "cmu4a1b2c000001s6xyz98765", "method": "PIX", "amount": 5000, "serviceFee": 50, "netAmount": 4950, "e2e": "E99999999202610051433a1b2c3d4e5f", "receiverPixKey": "b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03", "payer": { "name": "João Pereira", "document": "***.456.789-**", "bankIspb": "99999999", "bankName": "Banco Exemplo S.A." }, "paidAt": "2026-10-05T16:10:02.551Z", "createdAt": "2026-10-05T16:10:03.120Z", "refundedAmount": 0, "refundInProgressAmount": 0, "refundableAmount": 5000, "openInfractionProtocol": null, "refunds": [] } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "DEPOSIT_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "DEPOSIT_NOT_FOUND": { "summary": "DEPOSIT_NOT_FOUND", "value": { "message": "Depósito não encontrado.", "code": "DEPOSIT_NOT_FOUND" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/deposit/cmu4a1b2c000001s6xyz98765' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/deposit/cmu4a1b2c000001s6xyz98765';\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.hub.payzu.com.br/api/v1/transactions/deposit/cmu4a1b2c000001s6xyz98765',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/deposit/{depositId}/receipt": { "get": { "summary": "Comprovante do depósito", "description": "Escopo: `DEPOSIT_READ`.\n\nDevolve o comprovante do depósito em PDF, codificado em base64.", "operationId": "get_deposit_receipt", "tags": [ "Deposits" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "depositId", "required": true, "schema": { "type": "string" }, "example": "cmu4a1b2c000001s6xyz98765", "description": "Identificador do depósito." } ], "responses": { "200": { "description": "Comprovante.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "examples": { "Comprovante": { "summary": "Comprovante", "value": { "filename": "comprovante-pix-cmu4a1b2c000001s6xyz98765.pdf", "contentType": "application/pdf", "fileBase64": "JVBERi0xLjcKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nCvkMlAwUDC1NNUzMjNSMDEz" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "DEPOSIT_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "DEPOSIT_NOT_FOUND": { "summary": "DEPOSIT_NOT_FOUND", "value": { "message": "Depósito não encontrado.", "code": "DEPOSIT_NOT_FOUND" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/deposit/cmu4a1b2c000001s6xyz98765/receipt' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/deposit/cmu4a1b2c000001s6xyz98765/receipt';\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.hub.payzu.com.br/api/v1/transactions/deposit/cmu4a1b2c000001s6xyz98765/receipt',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/deposit/{depositId}/refund": { "post": { "summary": "Devolver depósito", "description": "Escopo: `REFUND`.\n\nDevolve ao pagador todo ou parte de um Pix recebido sem cobrança. Sem `amount`, devolve o que resta; a tarifa de estorno é somada por cima. O valor sai do saldo disponível na hora do pedido e volta se a devolução falhar. Uma devolução de cada vez; o resultado chega pelos webhooks `REFUND_COMPLETED` ou `REFUND_FAILED`, com `depositId`.", "operationId": "post_deposit_refund", "tags": [ "Deposits" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "depositId", "required": true, "schema": { "type": "string" }, "example": "cmu4a1b2c000001s6xyz98765", "description": "Identificador do depósito." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefund" }, "example": { "amount": 1000 } } } }, "responses": { "200": { "description": "O depósito atualizado, com a devolução em `refunds`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deposit" }, "examples": { "Devolução a caminho": { "summary": "Devolução a caminho", "value": { "id": "cmu4a1b2c000001s6xyz98765", "method": "PIX", "amount": 5000, "serviceFee": 50, "netAmount": 4950, "e2e": "E99999999202610051433a1b2c3d4e5f", "receiverPixKey": "b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03", "payer": { "name": "João Pereira", "document": "***.456.789-**", "bankIspb": "99999999", "bankName": "Banco Exemplo S.A." }, "paidAt": "2026-10-05T16:10:02.551Z", "createdAt": "2026-10-05T16:10:03.120Z", "refundedAmount": 0, "refundInProgressAmount": 5000, "refundableAmount": 0, "openInfractionProtocol": null, "refunds": [ { "id": "cmu7r2f9k000501s6ijkl9012", "status": "SENT", "amount": 5000, "serviceFee": 100, "totalDebited": 5100, "endToEndId": null, "rejectedReason": null, "requestedAt": "2026-10-06T10:05:00.000Z", "settledAt": null, "releasedAt": null } ] } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "REFUND_DISABLED": { "summary": "REFUND_DISABLED", "value": { "message": "Estorno desabilitado para esta conta.", "code": "REFUND_DISABLED" } }, "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "REFUND" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "DEPOSIT_NOT_FOUND": { "summary": "DEPOSIT_NOT_FOUND", "value": { "message": "Depósito não encontrado.", "code": "DEPOSIT_NOT_FOUND" } } } } } }, "412": { "description": "Falta um passo antes desta operação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ACCOUNT_NOT_OPERABLE": { "summary": "ACCOUNT_NOT_OPERABLE", "value": { "message": "Esta conta não está ativa e não pode movimentar dinheiro.", "code": "ACCOUNT_NOT_OPERABLE", "details": { "status": "CLOSED" } } }, "PROVIDER_NOT_PROVISIONED": { "summary": "PROVIDER_NOT_PROVISIONED", "value": { "message": "Esta conta ainda não terminou de ser aberta.", "code": "PROVIDER_NOT_PROVISIONED" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "REFUND_ALREADY_REFUNDED": { "summary": "REFUND_ALREADY_REFUNDED", "value": { "message": "Este pagamento já foi estornado integralmente.", "code": "REFUND_ALREADY_REFUNDED" } }, "REFUND_IN_FLIGHT": { "summary": "REFUND_IN_FLIGHT", "value": { "message": "Já existe um estorno em andamento para este pagamento. Aguarde o desfecho antes de pedir outro.", "code": "REFUND_IN_FLIGHT" } }, "REFUND_INFRACTION_OPEN": { "summary": "REFUND_INFRACTION_OPEN", "value": { "message": "Esta cobrança tem uma contestação MED em andamento; o estorno fica indisponível até o desfecho.", "code": "REFUND_INFRACTION_OPEN", "details": { "protocol": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d" } } }, "REFUND_ABOVE_REMAINING": { "summary": "REFUND_ABOVE_REMAINING", "value": { "message": "O valor do estorno é maior do que o que resta a devolver deste pagamento.", "code": "REFUND_ABOVE_REMAINING", "details": { "remaining": 500 } } }, "REFUND_ABOVE_TICKET_MAX": { "summary": "REFUND_ABOVE_TICKET_MAX", "value": { "message": "O valor do estorno está acima do limite por operação desta conta.", "code": "REFUND_ABOVE_TICKET_MAX", "details": { "max": 1000000 } } }, "REFUND_INSUFFICIENT_BALANCE": { "summary": "REFUND_INSUFFICIENT_BALANCE", "value": { "message": "Saldo insuficiente para estornar este pagamento.", "code": "REFUND_INSUFFICIENT_BALANCE", "details": { "available": 300, "required": 1600 } } }, "ACCOUNT_HELD_BY_STAFF": { "summary": "ACCOUNT_HELD_BY_STAFF", "value": { "message": "Esta conta está retida por decisão do suporte e não pode realizar operações até a liberação.", "code": "ACCOUNT_HELD_BY_STAFF" } }, "ACCOUNT_BLOCKED_BY_PROVIDER": { "summary": "ACCOUNT_BLOCKED_BY_PROVIDER", "value": { "message": "A conta tem um bloqueio na instituição parceira que impede esta operação até o desbloqueio.", "code": "ACCOUNT_BLOCKED_BY_PROVIDER", "details": { "operation": "PIX_OUT" } } }, "PROVIDER_OPERATION_UNAVAILABLE": { "summary": "PROVIDER_OPERATION_UNAVAILABLE", "value": { "message": "Operação indisponível para esta conta no momento.", "code": "PROVIDER_OPERATION_UNAVAILABLE" } } } } } }, "429": { "description": "Limite de requisições excedido.", "headers": { "Retry-After": { "description": "Segundos até poder repetir.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AUTH_TOO_MANY_REQUESTS": { "summary": "AUTH_TOO_MANY_REQUESTS", "value": { "message": "Muitas tentativas. Tente novamente em alguns minutos.", "code": "AUTH_TOO_MANY_REQUESTS", "details": { "retryAfterSeconds": 12 } } } } } } }, "502": { "description": "O banco não respondeu ou recusou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PROVIDER_UNAVAILABLE": { "summary": "PROVIDER_UNAVAILABLE", "value": { "message": "Não houve resposta a tempo. Tente de novo em instantes.", "code": "PROVIDER_UNAVAILABLE", "details": { "status": null, "reason": null } } }, "PROVIDER_REFUSED": { "summary": "PROVIDER_REFUSED", "value": { "message": "Esta operação foi recusada. Confira os dados enviados.", "code": "PROVIDER_REFUSED", "details": { "status": 422, "reason": "Operação recusada pelo banco." } } } } } } }, "503": { "description": "Serviço de consulta ou limitador indisponível; nada foi feito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_UNAVAILABLE": { "summary": "RATE_LIMIT_UNAVAILABLE", "value": { "message": "Proteção de limite indisponível. Tente novamente em instantes.", "code": "RATE_LIMIT_UNAVAILABLE" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/deposit/cmu4a1b2c000001s6xyz98765/refund' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"amount\": 1000\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/deposit/cmu4a1b2c000001s6xyz98765/refund';\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: 1000\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.hub.payzu.com.br/api/v1/transactions/deposit/cmu4a1b2c000001s6xyz98765/refund',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'amount': 1000\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/balance": { "get": { "summary": "Consultar saldo", "description": "Escopo: `STATEMENT_READ`.\n\nDevolve o saldo disponível e o bloqueado da conta, com o bloqueado separado por motivo.", "operationId": "get_balance", "tags": [ "Account" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Saldo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "examples": { "Saldo": { "summary": "Saldo", "value": { "total": 152030, "available": 150530, "blocked": 1500, "blockedBySecurity": 1500, "blockedByWithdraw": 0, "blockedByRefund": 0, "syncedAt": "2026-10-06T18:20:11.004Z" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "STATEMENT_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "412": { "description": "Falta um passo antes desta operação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PROVIDER_NOT_PROVISIONED": { "summary": "PROVIDER_NOT_PROVISIONED", "value": { "message": "Esta conta ainda não terminou de ser aberta.", "code": "PROVIDER_NOT_PROVISIONED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/balance' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/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.hub.payzu.com.br/api/v1/transactions/balance',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/statement": { "get": { "summary": "Consultar extrato", "description": "Escopo: `STATEMENT_READ`.\n\nDevolve os lançamentos que mexeram no saldo disponível, paginados por cursor. Cada linha é um lançamento, não uma operação: a cobrança paga entra já sem a tarifa, e o saque sai na hora do pedido, por `amount + serviceFee`. Os filtros valem juntos.", "operationId": "get_statement", "tags": [ "Account" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Itens por página, de 1 a 100." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" }, "description": "`nextCursor` da página anterior." }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string" }, "description": "Início do período, pela data de criação. ISO 8601 ou `AAAA-MM-DD`; data sem hora vale o dia inteiro no horário de Brasília." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string" }, "description": "Fim do período, pela data de criação. ISO 8601 ou `AAAA-MM-DD`; data sem hora vale o dia inteiro no horário de Brasília." }, { "in": "query", "name": "trigger", "required": false, "schema": { "type": "string" }, "example": "PAYMENT,DEPOSIT", "description": "Um ou mais tipos de linha, separados por vírgula: `PAYMENT`, `DEPOSIT`, `PAYMENT_REFUND`, `PAYOUT`, `PAYOUT_REVERSAL`, `PAYOUT_REFUND_RECEIVED`, `INFRACTION_BLOCK`, `INFRACTION_SETTLED`, `INFRACTION_RELEASED`, `INTERNAL_TRANSFER`." }, { "in": "query", "name": "originId", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Identificador da cobrança, do saque, do depósito ou da transferência como vem nos webhooks." }, { "in": "query", "name": "amount", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0 }, "description": "Valor em centavos, sem sinal. Encontra entradas e saídas desse valor e também operações com esse valor bruto." }, { "in": "query", "name": "e2e", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "End-to-end do Pix." }, { "in": "query", "name": "document", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Documento de quem pagou; pontuação é ignorada. Nas saídas, busca na chave de destino." }, { "in": "query", "name": "name", "required": false, "schema": { "type": "string", "minLength": 2 }, "description": "A partir de 2 caracteres, sem diferenciar maiúsculas. Nome de quem pagou nas entradas, chave nas saídas." }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELED", "REFUNDED", "WAITING_FOR_REFUND" ] }, "description": "Estado da operação de origem, não o `status` da linha. `PENDING`: cobrança aguardando pagamento ou saque ainda sendo processado. `COMPLETED`: cobrança paga, saque pago ou Pix recebido. `CANCELED`: cobrança vencida ou saque recusado. `REFUNDED`: cobrança com estorno concluído. `WAITING_FOR_REFUND`: cobrança com estorno ainda sendo processado. Traz as linhas dessas operações; linhas de transferência e de contestação ficam de fora." }, { "in": "query", "name": "sortBy", "required": false, "schema": { "default": "createdAt", "type": "string", "enum": [ "postedAt", "createdAt" ] }, "description": "Campo de ordenação." }, { "in": "query", "name": "sortDirection", "required": false, "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "description": "Direção da ordenação." } ], "responses": { "200": { "description": "Página do extrato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Statement" }, "examples": { "Página do extrato": { "summary": "Página do extrato", "value": { "data": [ { "id": "cmu9r1a2b000101s6stmt0002", "entryId": "cmu9r0z9y000001s6entr0002", "amount": -10250, "balanceAfter": 150530, "trigger": "PAYOUT", "description": "Reserva de saque", "originId": "cmu3wd7k1000201s6wdrw0001", "infractionProtocol": null, "gross": 10000, "fee": 250, "status": "SETTLED", "statusDetail": null, "statusReason": null, "statusAt": "2026-10-05T14:40:14.120Z", "payoutOperation": "WITHDRAW", "counterparty": { "name": null, "document": null, "pixKey": "f***@exemplo.com" }, "postedAt": "2026-10-05T14:40:11.002Z" }, { "id": "cmu9r1a2b000001s6stmt0001", "entryId": "cmu9r0z9y000001s6entr0001", "amount": 1395, "balanceAfter": 160780, "trigger": "PAYMENT", "description": "Pagamento recebido", "originId": "cmu2wbljx0000e8gtlic8q1gi", "infractionProtocol": null, "gross": 1500, "fee": 105, "status": null, "statusDetail": null, "statusReason": null, "statusAt": null, "payoutOperation": null, "counterparty": { "name": "Maria Souza", "document": "52998224725", "pixKey": null }, "postedAt": "2026-10-05T14:33:10.004Z" } ], "nextCursor": "cmu9r1a2b000001s6stmt0001", "balance": 150530 } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } }, "REQUEST_UNKNOWN_QUERY_PARAM": { "summary": "REQUEST_UNKNOWN_QUERY_PARAM", "value": { "message": "A requisição tem um parâmetro de busca que esta rota não conhece.", "code": "REQUEST_UNKNOWN_QUERY_PARAM", "details": { "unknownParams": [ "page" ], "accepted": [ "amount", "cursor", "dateFrom", "dateTo", "document", "e2e", "limit", "name", "originId", "sortBy", "sortDirection", "status", "trigger" ] } } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "STATEMENT_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/statement' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/statement';\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.hub.payzu.com.br/api/v1/transactions/statement',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/limits": { "get": { "summary": "Consultar limites e tarifas", "description": "Escopo: `STATEMENT_READ`.\n\nDevolve os limites por operação, as tarifas e os tetos diários que valem hoje para a conta. Valores em centavos e percentuais em basis points.", "operationId": "get_limits", "tags": [ "Account" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Limites e tarifas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountLimits" }, "examples": { "Limites e tarifas": { "summary": "Limites e tarifas", "value": { "payment": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 105, "feePercentage": 0 }, "withdraw": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 150 }, "externalPayment": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 0 }, "refund": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 0 }, "internalTransfer": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 0 }, "dailyWithdraw": { "limit": 1000000, "used": 12850 }, "dailyInternalTransfer": { "limit": null, "used": 0 }, "infraction": { "feeFixed": 500, "feePercentage": 0, "blocksBalance": true } } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "STATEMENT_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/limits' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/limits';\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.hub.payzu.com.br/api/v1/transactions/limits',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/metrics": { "get": { "summary": "Consultar métricas", "description": "Escopo: `STATEMENT_READ`.\n\nDevolve os números da conta no período: cobranças, conversão, estornos, contestações, saques e depósitos.", "operationId": "get_metrics", "tags": [ "Account" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string" }, "example": "2026-09-01", "description": "Início do período. Sem `dateFrom` e `dateTo`, valem os últimos 30 dias." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string" }, "example": "2026-09-30", "description": "Fim do período. ISO 8601 ou `AAAA-MM-DD`." } ], "responses": { "200": { "description": "Métricas do período.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountMetrics" }, "examples": { "Métricas de setembro": { "summary": "Métricas de setembro", "value": { "period": { "from": "2026-09-01T03:00:00.000Z", "to": "2026-10-01T02:59:59.999Z" }, "rails": [ { "method": "PIX", "available": true, "created": 120, "paid": 96, "conversionRate": 8000, "paidAmount": 480000, "averageTicket": 5000, "refundedAmount": 10000, "refundRate": 208, "disputedAmount": 0, "disputeRate": 0, "pending": 10, "pendingAmount": 50000, "refunded": 2 } ], "withdrawals": { "count": 4, "amount": 401000 }, "deposits": { "count": 3, "amount": 30000, "netAmount": 29700 }, "pixInflow": { "count": 99, "amount": 510000 } } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "STATEMENT_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/metrics' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/metrics';\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.hub.payzu.com.br/api/v1/transactions/metrics',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/infractions": { "get": { "summary": "Listar contestações MED", "description": "Escopo: `INFRACTION_READ`.\n\nDevolve as contestações MED da conta, da mais recente para a mais antiga pela data de abertura, paginadas por cursor. A resposta a uma contestação é feita no painel.", "operationId": "get_infractions", "tags": [ "Infractions" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Itens por página, de 1 a 100." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" }, "description": "`nextCursor` da página anterior." }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "OPEN", "ACKNOWLEDGED", "DEFENDED", "ANSWERED", "WAITING_PSP", "WAITING_ADJUSTMENTS", "CANCELLED", "CLOSED" ] }, "description": "Um estado exato. Com `status`, o `open` é ignorado." }, { "in": "query", "name": "open", "required": false, "schema": { "type": "boolean" }, "description": "`true` traz só as abertas: todo estado que não é `CLOSED` nem `CANCELLED`." }, { "in": "query", "name": "type", "required": false, "schema": { "type": "string", "enum": [ "REFUND_REQUEST", "FRAUD", "REFUND_CANCELLED" ] }, "description": "Motivo alegado." }, { "in": "query", "name": "analysisResult", "required": false, "schema": { "type": "string", "enum": [ "AGREED", "DISAGREED" ] }, "description": "Resultado da análise." } ], "responses": { "200": { "description": "Página de contestações.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfractionList" }, "examples": { "Página de contestações": { "summary": "Página de contestações", "value": { "data": [ { "id": "cmu6f0a1b000001s6abcd1234", "protocol": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d", "type": "REFUND_REQUEST", "status": "OPEN", "reportedBy": "DEBITED_PARTICIPANT", "reportDetails": "Cliente não reconhece a compra.", "analysisResult": null, "analysisDetails": null, "endToEndId": "E99999999202610051433a1b2c3d4e5f", "blockedAmount": 1500, "feeCharged": 0, "settledAmount": 0, "reportedAt": "2026-10-06T10:00:00.000Z", "dueAt": "2026-10-13T10:00:00.000Z", "closedAt": null, "origin": { "kind": "PAYMENT", "id": "cmu2wbljx0000e8gtlic8q1gi", "amount": 1500, "paidAt": "2026-10-05T14:33:10.004Z", "payerName": "Maria Souza", "payerDocument": "***.982.247-**" } } ] } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "INFRACTION_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/infractions' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/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.hub.payzu.com.br/api/v1/transactions/infractions',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/infractions/{protocol}": { "get": { "summary": "Consultar contestação MED", "description": "Escopo: `INFRACTION_READ`.\n\nDevolve uma contestação MED, com a etapa, o valor bloqueado e o resultado. Use o `protocol` que vem no webhook `INFRACTION_OPENED`.", "operationId": "get_infraction", "tags": [ "Infractions" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "protocol", "required": true, "schema": { "type": "string" }, "example": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d", "description": "Protocolo da contestação." } ], "responses": { "200": { "description": "Contestação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Infraction" }, "examples": { "Contestação aberta": { "summary": "Contestação aberta", "value": { "id": "cmu6f0a1b000001s6abcd1234", "protocol": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d", "type": "REFUND_REQUEST", "status": "OPEN", "reportedBy": "DEBITED_PARTICIPANT", "reportDetails": "Cliente não reconhece a compra.", "analysisResult": null, "analysisDetails": null, "endToEndId": "E99999999202610051433a1b2c3d4e5f", "blockedAmount": 1500, "feeCharged": 0, "settledAmount": 0, "reportedAt": "2026-10-06T10:00:00.000Z", "dueAt": "2026-10-13T10:00:00.000Z", "closedAt": null, "origin": { "kind": "PAYMENT", "id": "cmu2wbljx0000e8gtlic8q1gi", "amount": 1500, "paidAt": "2026-10-05T14:33:10.004Z", "payerName": "Maria Souza", "payerDocument": "***.982.247-**" } } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "INFRACTION_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "INFRACTION_NOT_FOUND": { "summary": "INFRACTION_NOT_FOUND", "value": { "message": "Contestação não encontrada.", "code": "INFRACTION_NOT_FOUND" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/infractions/b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/infractions/b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d';\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.hub.payzu.com.br/api/v1/transactions/infractions/b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/webhooks": { "get": { "summary": "Listar endpoints de webhook", "description": "Escopo: `WEBHOOK_READ`.\n\nDevolve os endpoints cadastrados na conta, do mais antigo para o mais novo. O segredo não é devolvido.", "operationId": "get_webhooks", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" }, "examples": { "Endpoints": { "summary": "Endpoints", "value": [ { "id": "cmu6w1h0k000101s6ef34gh56", "url": "https://sualoja.com.br/webhooks/payzu", "events": [ "PAYMENT_PAID", "PAYMENT_EXPIRED", "WITHDRAW_COMPLETED", "WITHDRAW_FAILED" ], "isActive": true, "createdAt": "2026-10-01T12:00:00.000Z", "updatedAt": "2026-10-01T12:00:00.000Z" } ] } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "WEBHOOK_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/webhooks' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/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.hub.payzu.com.br/api/v1/transactions/webhooks',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] }, "post": { "summary": "Cadastrar endpoint de webhook", "description": "Escopo: `WEBHOOK_WRITE`.\n\nRegistra uma URL para receber os webhooks dos eventos escolhidos. A resposta traz o segredo que assina os webhooks, e ele só aparece nela.", "operationId": "post_webhook", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhook" }, "example": { "url": "https://sualoja.com.br/webhooks/payzu", "events": [ "PAYMENT_PAID", "PAYMENT_EXPIRED", "WITHDRAW_COMPLETED", "WITHDRAW_FAILED" ] } } } }, "responses": { "201": { "description": "Endpoint cadastrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" }, "examples": { "Endpoint cadastrado": { "summary": "Endpoint cadastrado", "value": { "id": "cmu6w1h0k000101s6ef34gh56", "url": "https://sualoja.com.br/webhooks/payzu", "events": [ "PAYMENT_PAID", "PAYMENT_EXPIRED", "WITHDRAW_COMPLETED", "WITHDRAW_FAILED" ], "isActive": true, "createdAt": "2026-10-01T12:00:00.000Z", "updatedAt": "2026-10-01T12:00:00.000Z", "secret": "whsec_9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "WEBHOOK_WRITE" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "409": { "description": "Conflito com o estado atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "WEBHOOK_DUPLICATED_URL": { "summary": "WEBHOOK_DUPLICATED_URL", "value": { "message": "Já existe um webhook com esta URL nesta conta.", "code": "WEBHOOK_DUPLICATED_URL" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ACCOUNT_HELD_BY_STAFF": { "summary": "ACCOUNT_HELD_BY_STAFF", "value": { "message": "Esta conta está retida por decisão do suporte e não pode realizar operações até a liberação.", "code": "ACCOUNT_HELD_BY_STAFF" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/webhooks' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"url\": \"https://sualoja.com.br/webhooks/payzu\",\n \"events\": [\n \"PAYMENT_PAID\",\n \"PAYMENT_EXPIRED\",\n \"WITHDRAW_COMPLETED\",\n \"WITHDRAW_FAILED\"\n ]\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/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/webhooks/payzu',\n events: [\n 'PAYMENT_PAID',\n 'PAYMENT_EXPIRED',\n 'WITHDRAW_COMPLETED',\n 'WITHDRAW_FAILED'\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.hub.payzu.com.br/api/v1/transactions/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/webhooks/payzu',\n 'events': [\n 'PAYMENT_PAID',\n 'PAYMENT_EXPIRED',\n 'WITHDRAW_COMPLETED',\n 'WITHDRAW_FAILED'\n ]\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/webhooks/{webhookId}": { "put": { "summary": "Alterar endpoint de webhook", "description": "Escopo: `WEBHOOK_WRITE`.\n\nTroca a URL ou os eventos de um endpoint, ou o desativa e reativa. Envie ao menos um campo.", "operationId": "put_webhook", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "webhookId", "required": true, "schema": { "type": "string" }, "example": "cmu6w1h0k000101s6ef34gh56", "description": "Identificador do endpoint." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhook" }, "example": { "isActive": false } } } }, "responses": { "200": { "description": "Endpoint alterado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "examples": { "Endpoint desativado": { "summary": "Endpoint desativado", "value": { "id": "cmu6w1h0k000101s6ef34gh56", "url": "https://sualoja.com.br/webhooks/payzu", "events": [ "PAYMENT_PAID", "PAYMENT_EXPIRED", "WITHDRAW_COMPLETED", "WITHDRAW_FAILED" ], "isActive": false, "createdAt": "2026-10-01T12:00:00.000Z", "updatedAt": "2026-10-06T09:00:00.000Z" } } } } } }, "400": { "description": "Requisição inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SCHEMA_INVALID": { "summary": "SCHEMA_INVALID", "value": { "message": "A requisição contém valores inválidos.", "code": "SCHEMA_INVALID" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "WEBHOOK_WRITE" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "WEBHOOK_NOT_FOUND": { "summary": "WEBHOOK_NOT_FOUND", "value": { "message": "Webhook não encontrado.", "code": "WEBHOOK_NOT_FOUND" } } } } } }, "409": { "description": "Conflito com o estado atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "WEBHOOK_DUPLICATED_URL": { "summary": "WEBHOOK_DUPLICATED_URL", "value": { "message": "Já existe um webhook com esta URL nesta conta.", "code": "WEBHOOK_DUPLICATED_URL" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ACCOUNT_HELD_BY_STAFF": { "summary": "ACCOUNT_HELD_BY_STAFF", "value": { "message": "Esta conta está retida por decisão do suporte e não pode realizar operações até a liberação.", "code": "ACCOUNT_HELD_BY_STAFF" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request PUT \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/webhooks/cmu6w1h0k000101s6ef34gh56' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"isActive\": false\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/webhooks/cmu6w1h0k000101s6ef34gh56';\n\nconst response = await fetch(url, {\n method: 'PUT',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n isActive: false\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.put(\n 'https://api.hub.payzu.com.br/api/v1/transactions/webhooks/cmu6w1h0k000101s6ef34gh56',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'isActive': False\n },\n)\n\nprint(response.json())" } ] }, "delete": { "summary": "Excluir endpoint de webhook", "description": "Escopo: `WEBHOOK_WRITE`.\n\nRemove da conta um endpoint que ainda não teve entrega registrada. Com entrega registrada, a exclusão é recusada; nesse caso, desative com `isActive: false`.", "operationId": "delete_webhook", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "webhookId", "required": true, "schema": { "type": "string" }, "example": "cmu6w1h0k000101s6ef34gh56", "description": "Identificador do endpoint." } ], "responses": { "204": { "description": "Sem corpo." }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "WEBHOOK_WRITE" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "404": { "description": "Não encontrado, ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "WEBHOOK_NOT_FOUND": { "summary": "WEBHOOK_NOT_FOUND", "value": { "message": "Webhook não encontrado.", "code": "WEBHOOK_NOT_FOUND" } } } } } }, "409": { "description": "Conflito com o estado atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "WEBHOOK_HAS_DELIVERIES": { "summary": "WEBHOOK_HAS_DELIVERIES", "value": { "message": "Este endpoint já recebeu eventos e não pode ser excluído. Desative-o para parar de receber — o histórico de entregas é preservado.", "code": "WEBHOOK_HAS_DELIVERIES" } } } } } }, "422": { "description": "Recusa de regra de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ACCOUNT_HELD_BY_STAFF": { "summary": "ACCOUNT_HELD_BY_STAFF", "value": { "message": "Esta conta está retida por decisão do suporte e não pode realizar operações até a liberação.", "code": "ACCOUNT_HELD_BY_STAFF" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request DELETE \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/webhooks/cmu6w1h0k000101s6ef34gh56' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/webhooks/cmu6w1h0k000101s6ef34gh56';\n\nconst response = await fetch(url, {\n method: 'DELETE',\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconsole.log(response.status);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.delete(\n 'https://api.hub.payzu.com.br/api/v1/transactions/webhooks/cmu6w1h0k000101s6ef34gh56',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.status_code)" } ] } }, "/transactions/callback-secret": { "get": { "summary": "Consultar segredo de callback", "description": "Escopo: `WEBHOOK_READ`.\n\nDiz se a conta já tem segredo de callback. O valor não é devolvido.", "operationId": "get_callback_secret", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Situação do segredo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackSecretStatus" }, "examples": { "Segredo emitido": { "summary": "Segredo emitido", "value": { "hasCallbackSecret": true } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "WEBHOOK_READ" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/callback-secret' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/callback-secret';\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.hub.payzu.com.br/api/v1/transactions/callback-secret',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] }, "post": { "summary": "Emitir segredo de callback", "description": "Escopo: `WEBHOOK_WRITE`.\n\nGera o segredo de callback da conta, que assina os webhooks enviados à `callbackUrl` das operações. Sem ele, operação com `callbackUrl` é recusada. Se a conta já tem segredo, responde `409`.", "operationId": "post_callback_secret", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "201": { "description": "Segredo emitido. Só aparece nesta resposta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackSecret" }, "examples": { "Segredo": { "summary": "Segredo", "value": { "secret": "cbsec_2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "WEBHOOK_WRITE" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } }, "409": { "description": "Conflito com o estado atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CALLBACK_SECRET_ALREADY_ISSUED": { "summary": "CALLBACK_SECRET_ALREADY_ISSUED", "value": { "message": "Esta conta já tem um segredo de callback. Para trocá-lo, use a rotação.", "code": "CALLBACK_SECRET_ALREADY_ISSUED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/callback-secret' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/callback-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.hub.payzu.com.br/api/v1/transactions/callback-secret',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/transactions/callback-secret/rotate": { "post": { "summary": "Rotacionar segredo de callback", "description": "Escopo: `WEBHOOK_WRITE`.\n\nGera um segredo de callback novo. O anterior para de valer na hora.", "operationId": "post_callback_secret_rotate", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Segredo novo. Só aparece nesta resposta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackSecret" }, "examples": { "Segredo": { "summary": "Segredo", "value": { "secret": "cbsec_2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" } } } } } }, "401": { "description": "Credencial ausente, inválida ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_INVALID": { "summary": "TOKEN_INVALID", "value": { "message": "Credencial de integração inválida.", "code": "TOKEN_INVALID" } } } } } }, "403": { "description": "Sem permissão: escopo, IP ou operação desabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TOKEN_MISSING_SCOPE": { "summary": "TOKEN_MISSING_SCOPE", "value": { "message": "Esta credencial não tem permissão para esta operação.", "code": "TOKEN_MISSING_SCOPE", "details": { "scope": "WEBHOOK_WRITE" } } }, "TOKEN_IP_NOT_ALLOWED": { "summary": "TOKEN_IP_NOT_ALLOWED", "value": { "message": "Esta credencial não pode ser usada a partir deste IP.", "code": "TOKEN_IP_NOT_ALLOWED" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.hub.payzu.com.br/api/v1/transactions/callback-secret/rotate' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/transactions/callback-secret/rotate';\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.hub.payzu.com.br/api/v1/transactions/callback-secret/rotate',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n)\n\nprint(response.json())" } ] } }, "/status": { "get": { "summary": "Saúde do serviço", "description": "Diz se a API está respondendo. Não exige credencial. Responde `500` quando o serviço não está saudável.", "operationId": "get_status", "tags": [ "Status" ], "security": [], "responses": { "200": { "description": "Serviço respondendo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" }, "examples": { "Serviço respondendo": { "summary": "Serviço respondendo", "value": { "status": "ok", "updated_at": "2026-10-05T12:00:00.000Z" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.hub.payzu.com.br/api/v1/status'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "const url = 'https://api.hub.payzu.com.br/api/v1/status';\n\nconst response = await fetch(url, {\n method: 'GET',\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import requests\n\nresponse = requests.get(\n 'https://api.hub.payzu.com.br/api/v1/status',\n)\n\nprint(response.json())" } ] } } }, "webhooks": { "PAYMENT_CREATED": { "post": { "summary": "PAYMENT_CREATED", "description": "Cobrança registrada no banco.", "operationId": "webhook_payment_created", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "PAYMENT_CREATED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "PAYMENT_CREATED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/PaymentCreatedEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "PAYMENT_CREATED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "paymentId": "cmu2wbljx0000e8gtlic8q1gi", "status": "PENDING", "amount": 1500, "method": "PIX", "createdAt": "2026-10-05T14:32:05.123Z", "qrCode": "00020126580014br.gov.bcb.pix0136b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03520400005303986540515.005802BR5912LOJA EXEMPLO6009SAO PAULO62070503***63041EC4", "metadata": { "pedido": "4821", "canal": "checkout-web" }, "externalRef": "pedido-4821" } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "PAYMENT_PAID": { "post": { "summary": "PAYMENT_PAID", "description": "Cobrança paga.", "operationId": "webhook_payment_paid", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "PAYMENT_PAID" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "PAYMENT_PAID", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/PaymentSettledEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "PAYMENT_PAID", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "paymentId": "cmu2wbljx0000e8gtlic8q1gi", "status": "PAID", "amount": 1500, "serviceFee": 105, "netAmount": 1395, "endToEndId": "E99999999202610051433a1b2c3d4e5f", "metadata": { "pedido": "4821", "canal": "checkout-web" }, "externalRef": "pedido-4821" } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "PAYMENT_REFUNDED": { "post": { "summary": "PAYMENT_REFUNDED", "description": "O banco devolveu o pagamento ao pagador sem pedido seu. O valor cheio sai da conta.", "operationId": "webhook_payment_refunded", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "PAYMENT_REFUNDED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "PAYMENT_REFUNDED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/PaymentSettledEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "PAYMENT_REFUNDED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "paymentId": "cmu2wbljx0000e8gtlic8q1gi", "status": "REFUNDED", "amount": 1500, "serviceFee": 105, "netAmount": 1395, "debitedAmount": 1500, "serviceFeeReturned": false, "externalRef": "pedido-4821" } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "PAYMENT_EXPIRED": { "post": { "summary": "PAYMENT_EXPIRED", "description": "A cobrança venceu sem pagamento.", "operationId": "webhook_payment_expired", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "PAYMENT_EXPIRED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "PAYMENT_EXPIRED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/PaymentExpiredEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "PAYMENT_EXPIRED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "paymentId": "cmu2wbljx0000e8gtlic8q1gi", "status": "EXPIRED", "amount": 1500, "externalRef": "pedido-4821" } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "WITHDRAW_CREATED": { "post": { "summary": "WITHDRAW_CREATED", "description": "Saque pedido; o valor já saiu do saldo disponível.", "operationId": "webhook_withdraw_created", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "WITHDRAW_CREATED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "WITHDRAW_CREATED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/WithdrawEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "WITHDRAW_CREATED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "withdrawId": "cmu3wd7k1000201s6wdrw0001", "status": "REQUESTED", "operation": "WITHDRAW", "amount": 10000, "serviceFee": 250, "totalDebited": 10250, "pixKey": "fulano@exemplo.com" } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "WITHDRAW_COMPLETED": { "post": { "summary": "WITHDRAW_COMPLETED", "description": "O dinheiro chegou ao destino.", "operationId": "webhook_withdraw_completed", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "WITHDRAW_COMPLETED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "WITHDRAW_COMPLETED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/WithdrawEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "WITHDRAW_COMPLETED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "withdrawId": "cmu3wd7k1000201s6wdrw0001", "status": "CONFIRMED", "operation": "WITHDRAW", "amount": 10000, "serviceFee": 250, "totalDebited": 10250, "pixKey": "fulano@exemplo.com", "endToEndId": "E99999999202610051440f6e5d4c3b2a" } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "WITHDRAW_FAILED": { "post": { "summary": "WITHDRAW_FAILED", "description": "O saque falhou e o valor voltou ao saldo.", "operationId": "webhook_withdraw_failed", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "WITHDRAW_FAILED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "WITHDRAW_FAILED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/WithdrawEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "WITHDRAW_FAILED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "withdrawId": "cmu3wd7k1000201s6wdrw0001", "status": "FAILED", "operation": "WITHDRAW", "amount": 10000, "serviceFee": 250, "totalDebited": 10250, "pixKey": "fulano@exemplo.com", "reason": "O saque não foi concluído pelo banco de destino." } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "REFUND_COMPLETED": { "post": { "summary": "REFUND_COMPLETED", "description": "Estorno concluído: o valor voltou ao pagador.", "operationId": "webhook_refund_completed", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "REFUND_COMPLETED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "REFUND_COMPLETED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/RefundEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "REFUND_COMPLETED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "refundId": "cmu7r2f9k000301s6abcd5678", "paymentId": "cmu2wbljx0000e8gtlic8q1gi", "status": "SETTLED", "amount": 1000, "totalDebited": 1100, "endToEndId": "D99999999202610061010a9b8c7d6e5f" } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "REFUND_FAILED": { "post": { "summary": "REFUND_FAILED", "description": "Estorno recusado: o valor voltou ao saldo.", "operationId": "webhook_refund_failed", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "REFUND_FAILED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "REFUND_FAILED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/RefundEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "REFUND_FAILED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "refundId": "cmu7r2f9k000301s6abcd5678", "paymentId": "cmu2wbljx0000e8gtlic8q1gi", "status": "RELEASED", "amount": 1000, "totalDebited": 1100 } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "DEPOSIT_RECEIVED": { "post": { "summary": "DEPOSIT_RECEIVED", "description": "Pix recebido numa chave da conta sem cobrança.", "operationId": "webhook_deposit_received", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "DEPOSIT_RECEIVED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "DEPOSIT_RECEIVED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/DepositReceivedEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "DEPOSIT_RECEIVED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "depositId": "cmu4a1b2c000001s6xyz98765", "amount": 5000, "serviceFee": 50, "netAmount": 4950, "endToEndId": "E99999999202610051433a1b2c3d4e5f", "payerName": "João Pereira", "payerDocument": "12345678909" } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "INTERNAL_TRANSFER_SENT": { "post": { "summary": "INTERNAL_TRANSFER_SENT", "description": "A conta enviou uma transferência.", "operationId": "webhook_internal_transfer_sent", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "INTERNAL_TRANSFER_SENT" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "INTERNAL_TRANSFER_SENT", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/InternalTransferSentEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "INTERNAL_TRANSFER_SENT", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "transferId": "cmu3tr4n5000401s6trsf0001", "status": "CONFIRMED", "amount": 10000, "serviceFee": 100, "totalDebited": 10100, "toPixKey": "f***@lojaparceira.com.br" } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "INTERNAL_TRANSFER_RECEIVED": { "post": { "summary": "INTERNAL_TRANSFER_RECEIVED", "description": "A conta recebeu uma transferência.", "operationId": "webhook_internal_transfer_received", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "INTERNAL_TRANSFER_RECEIVED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "INTERNAL_TRANSFER_RECEIVED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/InternalTransferReceivedEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "INTERNAL_TRANSFER_RECEIVED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "transferId": "cmu3tr4n5000401s6trsf0001", "status": "CONFIRMED", "amount": 10000, "fromPixKey": "v***@sualoja.com.br" } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "WITHDRAW_REFUND_RECEIVED": { "post": { "summary": "WITHDRAW_REFUND_RECEIVED", "description": "Quem recebeu um Pix da conta devolveu o valor, inteiro ou em parte.", "operationId": "webhook_withdraw_refund_received", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "WITHDRAW_REFUND_RECEIVED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "WITHDRAW_REFUND_RECEIVED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/WithdrawRefundReceivedEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "WITHDRAW_REFUND_RECEIVED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "depositId": "cmu4a1b2c000201s6xyz11111", "withdrawId": "cmu3wd7k1000201s6wdrw0001", "amount": 10000, "originalAmount": 10000, "partial": false, "e2e": "D99999999202610061010a9b8c7d6e5f", "originalE2e": "E99999999202610051440f6e5d4c3b2a", "returnedAt": "2026-10-06T11:20:00.000Z" } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "INFRACTION_OPENED": { "post": { "summary": "INFRACTION_OPENED", "description": "Contestação MED aberta contra a conta.", "operationId": "webhook_infraction_opened", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "INFRACTION_OPENED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "INFRACTION_OPENED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/InfractionEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "INFRACTION_OPENED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "protocol": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d", "status": "OPEN", "paymentId": "cmu2wbljx0000e8gtlic8q1gi", "amount": 1500, "reportDetails": "Cliente não reconhece a compra.", "dueAt": "2026-10-13T10:00:00.000Z", "blockedAmount": 1500 } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "INFRACTION_CLOSED": { "post": { "summary": "INFRACTION_CLOSED", "description": "Contestação encerrada ou cancelada.", "operationId": "webhook_infraction_closed", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "INFRACTION_CLOSED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "INFRACTION_CLOSED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/InfractionEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "INFRACTION_CLOSED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "protocol": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d", "status": "CLOSED", "paymentId": "cmu2wbljx0000e8gtlic8q1gi", "amount": 1500, "reportDetails": "Cliente não reconhece a compra.", "analysisResult": "DISAGREED", "blockedAmount": 1500, "settledAmount": 0, "feeCharged": 500 } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "INFRACTION_DEADLINE": { "post": { "summary": "INFRACTION_DEADLINE", "description": "O prazo de resposta da contestação está chegando: faltam 48, 24 ou 6 horas.", "operationId": "webhook_infraction_deadline", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "INFRACTION_DEADLINE" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "INFRACTION_DEADLINE", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/InfractionDeadlineEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "INFRACTION_DEADLINE", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "protocol": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d", "paymentId": "cmu2wbljx0000e8gtlic8q1gi", "amount": 1500, "dueAt": "2026-10-13T10:00:00.000Z", "hoursRemaining": 24 } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "ACCOUNT_BLOCKED": { "post": { "summary": "ACCOUNT_BLOCKED", "description": "O banco bloqueou operações da conta, ou a lista de bloqueios mudou.", "operationId": "webhook_account_blocked", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "ACCOUNT_BLOCKED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "ACCOUNT_BLOCKED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/AccountBlockingEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "ACCOUNT_BLOCKED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "status": "SUSPENDED", "blockings": [ "PIX_OUT" ], "blockedOperations": [ "PIX_OUT" ], "changedAt": "2026-10-06T12:00:00.000Z" } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } }, "ACCOUNT_UNBLOCKED": { "post": { "summary": "ACCOUNT_UNBLOCKED", "description": "Os bloqueios da conta saíram.", "operationId": "webhook_account_unblocked", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Evento.", "example": "ACCOUNT_UNBLOCKED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Identificador da entrega. Igual em todas as tentativas e no reenvio: use para descartar entregas repetidas." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Instante desta tentativa, em milissegundos (Unix). Entra na assinatura." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` seguido do HMAC-SHA256, em hexadecimal, de `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "ACCOUNT_UNBLOCKED", "description": "Evento. O mesmo de `X-Payzu-Event`." }, "id": { "type": "string", "description": "Identificador da entrega, o mesmo de `X-Payzu-Delivery`. Igual em todas as tentativas e no reenvio." }, "sentAt": { "type": "string", "format": "date-time", "description": "Hora da primeira tentativa. Não muda nas seguintes." }, "accountId": { "type": "string", "description": "Conta que produziu o evento." }, "data": { "$ref": "#/components/schemas/AccountBlockingEvent", "description": "Corpo do evento." } }, "required": [ "event", "id", "sentAt", "accountId", "data" ] }, "example": { "event": "ACCOUNT_UNBLOCKED", "id": "cmu1r7x2k000a01s6h4f2b9qd", "sentAt": "2026-10-05T14:33:10.441Z", "accountId": "cmu0z8k2a000001s6acct0001", "data": { "status": "ACTIVE", "blockings": [], "blockedOperations": [], "changedAt": "2026-10-07T09:00:00.000Z" } } } } }, "responses": { "200": { "description": "Qualquer `2xx` em até 10 segundos confirma a entrega." } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Token de `POST /oauth/token` (15 minutos) ou o token da credencial `pzu__`." }, "BasicAuth": { "type": "http", "scheme": "basic", "description": "`client_id` e `client_secret` da credencial." } }, "schemas": { "Error": { "type": "object", "properties": { "message": { "type": "string", "description": "Descrição em português, pronta para exibir. Pode mudar a qualquer momento." }, "code": { "type": "string", "description": "Código estável do erro. É por ele que o seu sistema decide o que fazer." }, "details": { "type": "object", "additionalProperties": true, "description": "Contexto estruturado do erro, quando existe." } }, "required": [ "message", "code" ] }, "OAuthTokenRequest": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "Sempre `client_credentials`." }, "client_id": { "type": "string", "description": "`client_id` da credencial, quando não vai no header `Authorization: Basic`." }, "client_secret": { "type": "string", "description": "`client_secret` da credencial, quando não vai no header `Authorization: Basic`." } }, "required": [ "grant_type" ] }, "OAuthToken": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Token de acesso. Vai no header `Authorization: Bearer` das demais rotas." }, "token_type": { "type": "string", "enum": [ "Bearer" ], "description": "Sempre `Bearer`." }, "expires_in": { "type": "integer", "description": "Validade do token, em segundos." }, "scope": { "type": "string", "description": "Escopos da credencial, separados por espaço." } }, "required": [ "access_token", "token_type", "expires_in", "scope" ] }, "Status": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "`ok` quando o serviço responde." }, "updated_at": { "type": "string", "format": "date-time", "description": "Instante da resposta." } }, "required": [ "status", "updated_at" ] }, "CreatePayment": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Valor da cobrança, inteiro positivo. `1500` = R$ 15,00. Em centavos." }, "method": { "type": "string", "enum": [ "PIX" ], "description": "Meio de pagamento. Hoje só `PIX`." }, "description": { "type": [ "string", "null" ], "maxLength": 140, "description": "Texto exibido para quem paga." }, "externalRef": { "type": [ "string", "null" ], "maxLength": 64, "description": "Sua referência para a cobrança, única na conta. Repetir com os mesmos dados devolve a cobrança existente com `200`; com dados diferentes, `409`." }, "customer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Nome de quem paga." }, "document": { "type": "string", "minLength": 11, "description": "CPF ou CNPJ, com ou sem pontuação. O dígito verificador é conferido." }, "email": { "type": [ "string", "null" ], "maxLength": 120, "format": "email", "description": "E-mail de quem paga." }, "phone": { "type": [ "string", "null" ], "maxLength": 20, "description": "Telefone de quem paga." } }, "required": [ "name", "document" ], "description": "Quem vai pagar." }, "ipAddress": { "type": [ "string", "null" ], "description": "IP do comprador na sua loja. Guardado para análise de fraude e contestação; não volta em resposta nem webhook." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Objeto livre devolvido como veio nos webhooks `PAYMENT_*` desta cobrança. Até 20 chaves e 4 KB." }, "callbackUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "URL HTTPS pública que recebe todos os webhooks desta operação, além dos endpoints cadastrados. Até 2048 caracteres. Exige o segredo de callback da conta." } }, "required": [ "amount", "method", "customer" ] }, "RefundAttempt": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do estorno. É o `refundId` dos webhooks `REFUND_COMPLETED` e `REFUND_FAILED`." }, "status": { "type": "string", "enum": [ "RESERVED", "SENT", "SETTLED", "RELEASED" ], "description": "`RESERVED`: o valor saiu do saldo disponível. `SENT`: enviado ao banco. `SETTLED`: devolvido ao pagador. `RELEASED`: recusado, com o valor de volta ao saldo." }, "amount": { "type": "integer", "description": "Valor devolvido ao pagador. Em centavos." }, "serviceFee": { "type": "integer", "description": "Tarifa do estorno. Em centavos." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`: o que sai da conta. Em centavos." }, "endToEndId": { "type": [ "string", "null" ], "description": "End-to-end do Pix de devolução. `null` até concluir." }, "rejectedReason": { "type": [ "string", "null" ], "description": "Mensagem pronta para exibir, preenchida quando o banco recusou o estorno." }, "requestedAt": { "type": "string", "format": "date-time", "description": "Quando o estorno foi pedido. ISO 8601, UTC." }, "settledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando o estorno foi concluído. `null` até concluir." }, "releasedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando o valor voltou ao saldo, após recusa. `null` se não houve recusa." } }, "required": [ "id", "status", "amount", "serviceFee", "totalDebited", "endToEndId", "rejectedReason", "requestedAt", "settledAt", "releasedAt" ] }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador da cobrança. A consulta aceita este `id` e o `paymentId` dos webhooks." }, "method": { "type": "string", "enum": [ "PIX" ], "description": "Meio de pagamento." }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "REFUNDED", "EXPIRED" ], "description": "`PENDING`: aguardando pagamento. `PAID`: paga. `REFUNDED`: estornada por inteiro. `EXPIRED`: venceu sem pagamento." }, "amount": { "type": "integer", "description": "Valor cobrado. Em centavos." }, "description": { "type": [ "string", "null" ], "description": "Texto exibido para quem paga." }, "serviceFee": { "type": "integer", "description": "Tarifa do recebimento, descontada do valor. Em centavos." }, "netAmount": { "type": "integer", "description": "`amount − serviceFee`: o que é creditado na conta. Em centavos." }, "refundedAmount": { "type": "integer", "description": "Quanto já voltou ao pagador, só estornos concluídos. Em centavos." }, "refundFee": { "type": "integer", "description": "Tarifa cobrada nos estornos concluídos. Em centavos." }, "refundInProgressAmount": { "type": "integer", "description": "Estorno pedido e ainda sendo processado. Em centavos." }, "refundableAmount": { "type": "integer", "description": "Quanto ainda pode ser estornado. `0` enquanto a cobrança não foi paga, enquanto um estorno ainda está sendo processado e enquanto há contestação MED aberta. Em centavos." }, "openInfractionProtocol": { "type": [ "string", "null" ], "description": "Protocolo da contestação MED aberta sobre a cobrança. `null` quando não há." }, "externalRef": { "type": [ "string", "null" ], "description": "Sua referência, como enviada." }, "callbackUrl": { "type": [ "string", "null" ], "description": "A `callbackUrl` enviada na criação. `null` quando não foi enviada." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em ISO 8601, UTC." }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando foi paga. `null` até pagar." }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando foi estornada por inteiro. `null` até lá." }, "pix": { "type": [ "object", "null" ], "properties": { "qrCodeText": { "type": [ "string", "null" ], "description": "Pix copia e cola (BR Code). O QR Code é desenhado a partir deste texto." }, "qrCodeUrl": { "type": [ "string", "null" ], "description": "Sempre `null`." }, "qrCodeBase64": { "type": [ "string", "null" ], "description": "Sempre `null`." }, "conciliationId": { "type": [ "string", "null" ], "description": "End-to-end do Pix que pagou. `null` até pagar." } }, "required": [ "qrCodeText", "qrCodeUrl", "qrCodeBase64", "conciliationId" ], "description": "Dados do Pix da cobrança." }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "description": "Nome informado." }, "document": { "type": "string", "description": "Documento informado, só dígitos." }, "email": { "type": [ "string", "null" ], "description": "E-mail informado." }, "phone": { "type": [ "string", "null" ], "description": "Telefone informado." } }, "required": [ "name", "document", "email", "phone" ], "description": "Pagador como informado na criação." }, "payer": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Nome de quem pagou." }, "document": { "type": [ "string", "null" ], "description": "CPF mascarado (`***.982.247-**`) ou CNPJ formatado." }, "bankName": { "type": [ "string", "null" ], "description": "Instituição de quem pagou." } }, "required": [ "name", "document", "bankName" ], "description": "Quem de fato pagou, como o banco informou. `null` até pagar." }, "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/RefundAttempt" }, "description": "Estornos da cobrança, do mais recente para o mais antigo." } }, "required": [ "id", "method", "status", "amount", "description", "serviceFee", "netAmount", "refundedAmount", "refundFee", "refundInProgressAmount", "refundableAmount", "openInfractionProtocol", "externalRef", "callbackUrl", "createdAt", "paidAt", "refundedAt", "pix", "customer", "payer", "refunds" ] }, "PaymentListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador da cobrança." }, "method": { "type": "string", "enum": [ "PIX" ], "description": "Meio de pagamento." }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "REFUNDED", "EXPIRED" ], "description": "Estado da cobrança." }, "amount": { "type": "integer", "description": "Valor cobrado. Em centavos." }, "netAmount": { "type": "integer", "description": "O que é creditado na conta, já sem a tarifa. Em centavos." }, "refundedAmount": { "type": "integer", "description": "Quanto já voltou ao pagador, só estornos concluídos. Em centavos." }, "refundInProgressAmount": { "type": "integer", "description": "Estorno ainda sendo processado. Em centavos." }, "description": { "type": [ "string", "null" ], "description": "Texto exibido para quem paga." }, "payerName": { "type": [ "string", "null" ], "description": "Nome do pagador informado na criação." }, "payerDocument": { "type": [ "string", "null" ], "description": "Documento do pagador informado na criação, só dígitos." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em ISO 8601, UTC." }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando foi paga. `null` até pagar." } }, "required": [ "id", "method", "status", "amount", "netAmount", "refundedAmount", "refundInProgressAmount", "description", "payerName", "payerDocument", "createdAt", "paidAt" ] }, "PaymentList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentListItem" }, "description": "Cobranças da conta, da mais recente para a mais antiga." }, "nextCursor": { "type": "string", "description": "Cursor da próxima página. Ausente na última página." } }, "required": [ "data" ] }, "CreateRefund": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Valor a devolver. Sem ele, devolve o que resta. Em centavos." } } }, "Receipt": { "type": "object", "properties": { "filename": { "type": "string", "description": "Nome do arquivo." }, "contentType": { "type": "string", "enum": [ "application/pdf" ], "description": "Sempre `application/pdf`." }, "fileBase64": { "type": "string", "description": "PDF do comprovante, em base64." } }, "required": [ "filename", "contentType", "fileBase64" ] }, "CreateWithdraw": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "description": "Valor que chega ao destino. A tarifa é somada por cima. Em centavos." }, "pixKey": { "type": "string", "minLength": 1, "maxLength": 77, "description": "Chave Pix de destino." }, "pixKeyType": { "type": "string", "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Tipo da chave. Conferido contra a chave; sem ele, o tipo é deduzido do formato, e 11 dígitos podem ser CPF ou celular." }, "comment": { "type": "string", "maxLength": 140, "description": "Texto enviado ao destinatário, quando o banco dele exibe." }, "callbackUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "URL HTTPS pública que recebe todos os webhooks desta operação, além dos endpoints cadastrados. Até 2048 caracteres. Exige o segredo de callback da conta." } }, "required": [ "amount", "pixKey" ] }, "Withdraw": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do saque. A consulta aceita este `id` e o `withdrawId` dos webhooks." }, "status": { "type": "string", "enum": [ "REQUESTED", "CREATED", "APPROVED", "CONFIRMED", "FAILED" ], "description": "`REQUESTED`: pedido feito; o valor já saiu do saldo disponível. `CREATED`: registrado no banco. `APPROVED`: aprovado, a caminho. `CONFIRMED`: o dinheiro chegou. `FAILED`: não saiu, e o valor voltou ao saldo; pode vir de `REQUESTED`, `CREATED` ou `APPROVED`." }, "amount": { "type": "integer", "description": "Valor que chega ao destino. Em centavos." }, "serviceFee": { "type": "integer", "description": "Tarifa, somada por cima. Em centavos." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`: o que sai da conta. Em centavos." }, "pixKey": { "type": "string", "description": "Chave de destino. No saque, a chave enviada, normalizada; no pagamento de Pix copia e cola, mascarada (CPF, e-mail e telefone saem mascarados; CNPJ e chave aleatória, legíveis.)" }, "comment": { "type": [ "string", "null" ], "description": "Texto enviado ao destinatário." }, "e2e": { "type": [ "string", "null" ], "description": "End-to-end do Pix. `null` até o banco registrar." }, "providerRejectedReason": { "type": [ "string", "null" ], "description": "Mensagem pronta para exibir, preenchida quando o banco recusou." }, "callbackUrl": { "type": [ "string", "null" ], "description": "A `callbackUrl` enviada na criação. `null` quando não foi enviada." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em ISO 8601, UTC." }, "sentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando o banco registrou o saque." }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando o banco aprovou o saque." }, "confirmedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando o dinheiro chegou ao destino." } }, "required": [ "id", "status", "amount", "serviceFee", "totalDebited", "pixKey", "comment", "e2e", "providerRejectedReason", "callbackUrl", "createdAt", "sentAt", "approvedAt", "confirmedAt" ] }, "WithdrawDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do saque. A consulta aceita este `id` e o `withdrawId` dos webhooks." }, "status": { "type": "string", "enum": [ "REQUESTED", "CREATED", "APPROVED", "CONFIRMED", "FAILED" ], "description": "`REQUESTED`: pedido feito; o valor já saiu do saldo disponível. `CREATED`: registrado no banco. `APPROVED`: aprovado, a caminho. `CONFIRMED`: o dinheiro chegou. `FAILED`: não saiu, e o valor voltou ao saldo; pode vir de `REQUESTED`, `CREATED` ou `APPROVED`." }, "operation": { "type": "string", "enum": [ "WITHDRAW", "EXTERNAL_PAYMENT" ], "description": "`WITHDRAW`: saque para uma chave. `EXTERNAL_PAYMENT`: pagamento de Pix copia e cola." }, "amount": { "type": "integer", "description": "Valor que chega ao destino. Em centavos." }, "serviceFee": { "type": "integer", "description": "Tarifa, somada por cima. Em centavos." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`: o que sai da conta. Em centavos." }, "destination": { "type": "object", "properties": { "pixKey": { "type": "string", "description": "Chave de destino, mascarada: CPF, e-mail e telefone saem mascarados; CNPJ e chave aleatória, legíveis." }, "pixKeyType": { "type": [ "string", "null" ], "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Tipo da chave, deduzido do formato." } }, "required": [ "pixKey", "pixKeyType" ], "description": "Destino do saque." }, "comment": { "type": [ "string", "null" ], "description": "Texto enviado ao destinatário." }, "e2e": { "type": [ "string", "null" ], "description": "End-to-end do Pix. `null` até o banco registrar." }, "providerRejectedReason": { "type": [ "string", "null" ], "description": "Mensagem pronta para exibir, preenchida quando o banco recusou." }, "callbackUrl": { "type": [ "string", "null" ], "description": "A `callbackUrl` enviada na criação. `null` quando não foi enviada." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em ISO 8601, UTC." }, "sentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando o banco registrou o saque." }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando o banco aprovou o saque." }, "confirmedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando o dinheiro chegou ao destino." }, "failedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando o saque falhou. `null` se não falhou." } }, "required": [ "id", "status", "operation", "amount", "serviceFee", "totalDebited", "destination", "comment", "e2e", "providerRejectedReason", "callbackUrl", "createdAt", "sentAt", "approvedAt", "confirmedAt", "failedAt" ] }, "WithdrawListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do saque. A consulta aceita este `id` e o `withdrawId` dos webhooks." }, "status": { "type": "string", "enum": [ "REQUESTED", "CREATED", "APPROVED", "CONFIRMED", "FAILED" ], "description": "`REQUESTED`: pedido feito; o valor já saiu do saldo disponível. `CREATED`: registrado no banco. `APPROVED`: aprovado, a caminho. `CONFIRMED`: o dinheiro chegou. `FAILED`: não saiu, e o valor voltou ao saldo; pode vir de `REQUESTED`, `CREATED` ou `APPROVED`." }, "operation": { "type": "string", "enum": [ "WITHDRAW", "EXTERNAL_PAYMENT" ], "description": "`WITHDRAW`: saque para uma chave. `EXTERNAL_PAYMENT`: pagamento de Pix copia e cola." }, "amount": { "type": "integer", "description": "Valor que chega ao destino. Em centavos." }, "serviceFee": { "type": "integer", "description": "Tarifa, somada por cima. Em centavos." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`: o que sai da conta. Em centavos." }, "destination": { "type": "object", "properties": { "pixKey": { "type": "string", "description": "Chave de destino, mascarada: CPF, e-mail e telefone saem mascarados; CNPJ e chave aleatória, legíveis." }, "pixKeyType": { "type": [ "string", "null" ], "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Tipo da chave, deduzido do formato." } }, "required": [ "pixKey", "pixKeyType" ], "description": "Destino do saque." }, "comment": { "type": [ "string", "null" ], "description": "Texto enviado ao destinatário." }, "e2e": { "type": [ "string", "null" ], "description": "End-to-end do Pix. `null` até o banco registrar." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em ISO 8601, UTC." }, "confirmedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando o dinheiro chegou ao destino." } }, "required": [ "id", "status", "operation", "amount", "serviceFee", "totalDebited", "destination", "comment", "e2e", "createdAt", "confirmedAt" ] }, "WithdrawList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawListItem" }, "description": "Saques e pagamentos de Pix copia e cola da conta, da mais recente para a mais antiga." }, "nextCursor": { "type": "string", "description": "Cursor da próxima página. Ausente na última página." } }, "required": [ "data" ] }, "PayQrCode": { "type": "object", "properties": { "brCode": { "type": "string", "minLength": 8, "maxLength": 1024, "description": "Pix copia e cola, completo, como foi lido." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Valor a pagar, quando o código não traz valor. Se traz, deve ser igual ao do código. Em centavos." }, "comment": { "type": "string", "maxLength": 140, "description": "Texto enviado ao destinatário. Sem ele, vai o nome do destinatário que está no código." }, "callbackUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "URL HTTPS pública que recebe todos os webhooks desta operação, além dos endpoints cadastrados. Até 2048 caracteres. Exige o segredo de callback da conta." } }, "required": [ "brCode" ] }, "DecodeQrCode": { "type": "object", "properties": { "brCode": { "type": "string", "minLength": 8, "maxLength": 1024, "description": "Pix copia e cola." } }, "required": [ "brCode" ] }, "DecodedQrCode": { "type": "object", "properties": { "pixKey": { "type": [ "string", "null" ], "description": "Chave Pix que o código carrega, inteira. `null` em código dinâmico." }, "url": { "type": [ "string", "null" ], "description": "Endereço com os dados do código dinâmico. `null` no estático." }, "amount": { "type": [ "integer", "null" ], "description": "Valor fixado no código. `null` quando o pagador escolhe. Em centavos." }, "merchantName": { "type": [ "string", "null" ], "description": "Nome escrito por quem gerou o código. Não é verificado." }, "merchantCity": { "type": [ "string", "null" ], "description": "Cidade escrita por quem gerou o código. Não é verificada." }, "txid": { "type": [ "string", "null" ], "description": "Identificador que o destinatário pôs no código." }, "isDynamic": { "type": "boolean", "description": "`true` quando o código é de uso único." }, "isAmountFixed": { "type": "boolean", "description": "`true` quando `amount` não é `null`." } }, "required": [ "pixKey", "url", "amount", "merchantName", "merchantCity", "txid", "isDynamic", "isAmountFixed" ] }, "PixDestinationRequest": { "type": "object", "properties": { "pixKey": { "type": "string", "minLength": 1, "maxLength": 140, "description": "Chave Pix a consultar. Envie `pixKey` ou `brCode`, nunca os dois." }, "pixKeyType": { "type": "string", "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Tipo da chave. Só com `pixKey`." }, "brCode": { "type": "string", "minLength": 8, "maxLength": 1024, "description": "Pix copia e cola a consultar." } } }, "PixDestination": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "PIX_KEY", "BR_CODE" ], "description": "O que foi consultado: `PIX_KEY` ou `BR_CODE`." }, "pixKey": { "type": "string", "description": "Chave de destino. CPF, e-mail e telefone saem mascarados; CNPJ e chave aleatória, legíveis." }, "pixKeyType": { "type": [ "string", "null" ], "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Tipo da chave, deduzido do formato. `null` quando o formato não é reconhecido." }, "holder": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Nome do titular, por extenso." }, "document": { "type": [ "string", "null" ], "description": "CPF mascarado ou CNPJ formatado." } }, "required": [ "name", "document" ], "description": "Titular da chave. `null` quando não há nome nem documento." }, "bank": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Nome da instituição." }, "ispb": { "type": [ "string", "null" ], "description": "ISPB da instituição." }, "branch": { "type": [ "string", "null" ], "description": "Agência." }, "accountNumber": { "type": [ "string", "null" ], "description": "Conta mascarada, com os quatro últimos dígitos visíveis." } }, "required": [ "name", "ispb", "branch", "accountNumber" ], "description": "Instituição do destino. `null` quando a consulta não aconteceu." }, "amount": { "type": [ "integer", "null" ], "description": "Valor fixado no Pix copia e cola. Sempre `null` para chave. Em centavos." }, "isAmountFixed": { "type": "boolean", "description": "`true` quando `amount` não é `null`." }, "isVerified": { "type": "boolean", "description": "`true` quando o nome veio do DICT; `false` quando veio do próprio Pix copia e cola." } }, "required": [ "source", "pixKey", "pixKeyType", "holder", "bank", "amount", "isAmountFixed", "isVerified" ] }, "CreatePixKey": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Tipo da chave. Hoje dá para criar `EVP` e `CNPJ`." }, "key": { "type": "string", "minLength": 1, "description": "Valor da chave. Obrigatório, exceto em `EVP`, em que não deve ser enviado. CPF e CNPJ precisam ser do titular da conta." } }, "required": [ "type" ] }, "PixKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador da chave. É o que vai nas rotas de apagar e de definir a padrão." }, "key": { "type": "string", "description": "Valor da chave, inteiro." }, "type": { "type": "string", "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Tipo da chave." }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "REMOVED" ], "description": "Estado da chave." }, "isDefault": { "type": "boolean", "description": "Se é a chave padrão da conta." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em ISO 8601, UTC." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data e hora em ISO 8601, UTC." } }, "required": [ "id", "key", "type", "status", "isDefault", "createdAt", "updatedAt" ] }, "PixKeyList": { "type": "array", "items": { "$ref": "#/components/schemas/PixKey" } }, "CreateInternalTransfer": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "description": "Valor que chega ao destino. A tarifa é somada por cima. Em centavos." }, "toPixKey": { "type": "string", "minLength": 1, "maxLength": 77, "description": "Chave Pix de outra conta PayZu." }, "comment": { "type": "string", "maxLength": 140, "description": "Texto que aparece no comprovante." }, "callbackUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "URL HTTPS pública que recebe todos os webhooks desta operação, além dos endpoints cadastrados. Até 2048 caracteres. Exige o segredo de callback da conta. O webhook `INTERNAL_TRANSFER_RECEIVED`, da conta de destino, não vai para ela." } }, "required": [ "amount", "toPixKey" ] }, "InternalTransfer": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador da transferência. A consulta aceita este `id` e o `transferId` dos webhooks." }, "status": { "type": "string", "enum": [ "REQUESTED", "CONFIRMED", "FAILED" ], "description": "`REQUESTED`: ainda sem resultado, depois de um `502` em que o banco não respondeu ou recusou temporariamente. `CONFIRMED`: o valor está na outra conta. `FAILED`: não saiu." }, "side": { "type": "string", "enum": [ "SENT", "RECEIVED" ], "description": "Ponta em que a sua conta está: `SENT` (enviou) ou `RECEIVED` (recebeu)." }, "amount": { "type": "integer", "description": "Valor que chegou ao destino. Em centavos." }, "serviceFee": { "type": "integer", "description": "Tarifa. `0` do lado de quem recebe. Em centavos." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`. `0` do lado de quem recebe. Em centavos." }, "counterparty": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome da outra conta." }, "document": { "type": "string", "description": "Documento da outra conta: CPF mascarado ou CNPJ formatado. Vazio quando não é conhecido." }, "pixKey": { "type": "string", "description": "Chave da outra conta. Inteira na resposta do `POST`; na consulta e na listagem, CPF, e-mail e telefone saem mascarados." } }, "required": [ "name", "document", "pixKey" ], "description": "A outra conta." }, "comment": { "type": [ "string", "null" ], "description": "Texto do comprovante." }, "providerRejectedReason": { "type": [ "string", "null" ], "description": "Mensagem pronta para exibir, preenchida quando `FAILED`." }, "callbackUrl": { "type": [ "string", "null" ], "description": "A `callbackUrl` enviada na criação. `null` quando não foi enviada. `null` do lado de quem recebeu." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em ISO 8601, UTC." }, "confirmedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando foi concluída. `null` até concluir." }, "failedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando falhou. `null` se não falhou." } }, "required": [ "id", "status", "side", "amount", "serviceFee", "totalDebited", "counterparty", "comment", "providerRejectedReason", "callbackUrl", "createdAt", "confirmedAt", "failedAt" ] }, "InternalTransferList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InternalTransfer" }, "description": "Transferências enviadas e recebidas, da mais recente para a mais antiga." }, "nextCursor": { "type": "string", "description": "Cursor da próxima página. Ausente na última página." } }, "required": [ "data" ] }, "Deposit": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do depósito." }, "method": { "type": "string", "enum": [ "PIX" ], "description": "Sempre `PIX`." }, "amount": { "type": "integer", "description": "Valor que o pagador mandou. Em centavos." }, "serviceFee": { "type": "integer", "description": "Tarifa do recebimento. Em centavos." }, "netAmount": { "type": "integer", "description": "`amount − serviceFee`: o que foi creditado. Em centavos." }, "e2e": { "type": "string", "description": "End-to-end do Pix recebido." }, "receiverPixKey": { "type": [ "string", "null" ], "description": "Chave da sua conta que recebeu." }, "payer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Nome de quem pagou." }, "document": { "type": [ "string", "null" ], "description": "CPF mascarado ou CNPJ formatado." }, "bankIspb": { "type": [ "string", "null" ], "description": "ISPB da instituição de quem pagou." }, "bankName": { "type": [ "string", "null" ], "description": "Instituição de quem pagou." } }, "required": [ "name", "document", "bankIspb", "bankName" ], "description": "Quem pagou, como o banco informou." }, "paidAt": { "type": "string", "format": "date-time", "description": "Quando o Pix caiu." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em ISO 8601, UTC." }, "refundedAmount": { "type": "integer", "description": "Quanto já foi devolvido, só devoluções concluídas. Em centavos." }, "refundInProgressAmount": { "type": "integer", "description": "Devolução ainda sendo processada. Em centavos." }, "refundableAmount": { "type": "integer", "description": "Quanto ainda pode ser devolvido. `0` enquanto uma devolução ainda está sendo processada ou há contestação aberta. Em centavos." }, "openInfractionProtocol": { "type": [ "string", "null" ], "description": "Protocolo da contestação MED aberta sobre o depósito. `null` quando não há." }, "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/RefundAttempt" }, "description": "Devoluções do depósito, da mais recente para a mais antiga." } }, "required": [ "id", "method", "amount", "serviceFee", "netAmount", "e2e", "receiverPixKey", "payer", "paidAt", "createdAt", "refundedAmount", "refundInProgressAmount", "refundableAmount", "openInfractionProtocol", "refunds" ] }, "Balance": { "type": "object", "properties": { "total": { "type": "integer", "description": "`available + blocked`. Em centavos." }, "available": { "type": "integer", "description": "Saldo disponível para saque, pagamento de Pix copia e cola e estorno. É o total das linhas do extrato. Em centavos." }, "blocked": { "type": "integer", "description": "Saldo na conta que não pode ser usado: a soma dos três campos abaixo. Em centavos." }, "blockedBySecurity": { "type": "integer", "description": "Preso por contestação MED aberta e por outros bloqueios que não são de saque nem de estorno, como o valor de uma transferência ainda sem resultado. Em centavos." }, "blockedByWithdraw": { "type": "integer", "description": "Preso por saque ainda sendo processado. Em centavos." }, "blockedByRefund": { "type": "integer", "description": "Preso por estorno ainda sendo processado. Em centavos." }, "syncedAt": { "type": "string", "format": "date-time", "description": "Instante da resposta." } }, "required": [ "total", "available", "blocked", "blockedBySecurity", "blockedByWithdraw", "blockedByRefund", "syncedAt" ] }, "StatementEntry": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador da linha. É o valor usado como cursor." }, "entryId": { "type": "string", "description": "Lançamento. Linhas com o mesmo `entryId` vieram do mesmo evento." }, "amount": { "type": "integer", "description": "Valor com sinal: positivo entrou, negativo saiu. Em centavos." }, "balanceAfter": { "type": "integer", "description": "Saldo disponível depois da linha. Em centavos." }, "trigger": { "type": "string", "enum": [ "PAYMENT", "PAYMENT_REFUND", "DEPOSIT", "PAYOUT", "PAYOUT_REVERSAL", "INFRACTION_BLOCK", "INFRACTION_SETTLED", "INFRACTION_RELEASED", "INTERNAL_TRANSFER", "PAYOUT_REFUND_RECEIVED" ], "description": "O que produziu a linha. `PAYMENT`: cobrança paga. `DEPOSIT`: Pix recebido sem cobrança. `PAYMENT_REFUND`: estorno. `PAYOUT`: saída de saque ou pagamento de Pix copia e cola, na hora do pedido. `PAYOUT_REVERSAL`: valor de volta ao saldo após falha. `PAYOUT_REFUND_RECEIVED`: devolução de um Pix enviado. `INFRACTION_BLOCK`: contestação aberta. `INFRACTION_SETTLED`: contestação procedente. `INFRACTION_RELEASED`: contestação improcedente ou cancelada. `INTERNAL_TRANSFER`: transferência entre contas." }, "description": { "type": [ "string", "null" ], "description": "Rótulo curto, gravado com o lançamento. Não muda depois; o estado atual está em `status`." }, "originId": { "type": "string", "description": "Identificador da operação (cobrança, saque, depósito ou transferência) como vem nos webhooks; não é o `id` da cobrança, do saque ou da transferência. Nas linhas de MED, o da contestação." }, "infractionProtocol": { "type": [ "string", "null" ], "description": "Protocolo da contestação, nas linhas de MED." }, "gross": { "type": [ "integer", "null" ], "description": "Valor cheio da operação. No recebimento, o que o pagador pagou; no saque, o que chegou ao destino. Em centavos." }, "fee": { "type": [ "integer", "null" ], "description": "Tarifa da operação. Em centavos." }, "status": { "type": [ "string", "null" ], "enum": [ "PROCESSING", "SETTLED", "RETURNED" ], "description": "Estado atual da operação da linha, em saque, estorno e transferência: `PROCESSING`, `SETTLED` ou `RETURNED`. `null` nas demais." }, "statusDetail": { "type": [ "string", "null" ], "enum": [ "APPROVAL_REFUSED", "PROVIDER_REFUND" ], "description": "`APPROVAL_REFUSED`: o banco não aprovou o saque, e o valor continua fora do saldo disponível. `PROVIDER_REFUND`: o banco devolveu ao pagador sem pedido seu." }, "statusReason": { "type": [ "string", "null" ], "description": "Mensagem pronta para exibir, em `APPROVAL_REFUSED`." }, "statusAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando a operação concluiu ou voltou." }, "payoutOperation": { "type": [ "string", "null" ], "enum": [ "WITHDRAW", "EXTERNAL_PAYMENT" ], "description": "Nas linhas de saque: `WITHDRAW` (saque para chave) ou `EXTERNAL_PAYMENT` (pagamento de Pix copia e cola)." }, "counterparty": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Nas entradas, nome de quem pagou; numa cobrança, o cliente informado. `null` nas saídas por Pix." }, "document": { "type": [ "string", "null" ], "description": "Documento dessa pessoa. Numa cobrança, inteiro; num Pix avulso, mascarado." }, "pixKey": { "type": [ "string", "null" ], "description": "Nas saídas, chave de destino mascarada. Na transferência entre contas, a chave da outra conta." } }, "required": [ "name", "document", "pixKey" ], "description": "Com quem foi a operação. `null` nas linhas de contestação." }, "postedAt": { "type": "string", "format": "date-time", "description": "Quando o dinheiro se moveu." } }, "required": [ "id", "entryId", "amount", "balanceAfter", "trigger", "description", "originId", "infractionProtocol", "gross", "fee", "status", "statusDetail", "statusReason", "statusAt", "payoutOperation", "counterparty", "postedAt" ] }, "Statement": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatementEntry" }, "description": "Linhas do extrato." }, "nextCursor": { "type": "string", "description": "Cursor da próxima página. Ausente na última página." }, "balance": { "type": "integer", "description": "Saldo disponível agora, igual a `available` do saldo. Em centavos." } }, "required": [ "data", "balance" ] }, "OperationLimits": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Se a operação está liberada para a conta." }, "ticketMin": { "type": "integer", "description": "Menor valor por operação. Em centavos." }, "ticketMax": { "type": "integer", "description": "Maior valor por operação. Em centavos." }, "feeFixed": { "type": "integer", "description": "Parte fixa da tarifa. Em centavos." }, "feePercentage": { "type": "integer", "description": "Parte percentual da tarifa, em basis points (`150` = 1,5%)." } }, "required": [ "enabled", "ticketMin", "ticketMax", "feeFixed", "feePercentage" ] }, "DailyLimit": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "description": "Teto diário. `null` é sem teto; `0` bloqueia toda operação. Em centavos." }, "used": { "type": "integer", "description": "Quanto do teto já foi usado hoje, no horário de Brasília. Sem teto, `0`. Em centavos." } }, "required": [ "limit", "used" ] }, "AccountLimits": { "type": "object", "properties": { "payment": { "$ref": "#/components/schemas/OperationLimits", "description": "Cobrança." }, "withdraw": { "$ref": "#/components/schemas/OperationLimits", "description": "Saque para chave. O mínimo e o máximo valem para toda saída por Pix." }, "externalPayment": { "$ref": "#/components/schemas/OperationLimits", "description": "Pagamento de Pix copia e cola: limites do saque, com tarifa própria." }, "refund": { "$ref": "#/components/schemas/OperationLimits", "description": "Estorno e devolução de depósito. O máximo por operação é o do saque; o mínimo não é conferido." }, "internalTransfer": { "$ref": "#/components/schemas/OperationLimits", "description": "Transferência entre contas PayZu." }, "dailyWithdraw": { "$ref": "#/components/schemas/DailyLimit", "description": "Teto diário das saídas por Pix." }, "dailyInternalTransfer": { "$ref": "#/components/schemas/DailyLimit", "description": "Teto diário das transferências entre contas." }, "infraction": { "type": "object", "properties": { "feeFixed": { "type": "integer", "description": "Parte fixa da taxa de análise de contestação improcedente. Em centavos." }, "feePercentage": { "type": "integer", "description": "Parte percentual da taxa de análise, em basis points." }, "blocksBalance": { "type": "boolean", "description": "Se o valor contestado sai do saldo disponível enquanto a análise corre." } }, "required": [ "feeFixed", "feePercentage", "blocksBalance" ], "description": "Contestação MED." } }, "required": [ "payment", "withdraw", "externalPayment", "refund", "internalTransfer", "dailyWithdraw", "dailyInternalTransfer", "infraction" ] }, "RailMetrics": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "PIX", "BOLETO", "CREDITCARD" ], "description": "Meio de pagamento." }, "available": { "type": "boolean", "const": true, "description": "`true`: há métricas para o meio. O Pix sem cobranças no período vem com os números zerados." }, "created": { "type": "integer", "description": "Cobranças criadas no período." }, "paid": { "type": "integer", "description": "Cobranças do período que foram pagas, inclusive as estornadas depois." }, "conversionRate": { "type": [ "integer", "null" ], "description": "`paid / created`, em basis points. `null` sem cobranças." }, "paidAmount": { "type": "integer", "description": "Soma bruta do que foi pago. Em centavos." }, "averageTicket": { "type": [ "integer", "null" ], "description": "`paidAmount / paid`. `null` sem pagamentos. Em centavos." }, "refundedAmount": { "type": "integer", "description": "Devolvido ao pagador, inclusive estorno parcial. Em centavos." }, "refundRate": { "type": [ "integer", "null" ], "description": "Proporção estornada, em basis points. `null` sem base." }, "disputedAmount": { "type": "integer", "description": "Valor sob contestação MED. Em centavos." }, "disputeRate": { "type": [ "integer", "null" ], "description": "Proporção contestada, em basis points. `null` sem base." }, "pending": { "type": "integer", "description": "Cobranças do período ainda não pagas." }, "pendingAmount": { "type": "integer", "description": "Soma das cobranças não pagas. Em centavos." }, "refunded": { "type": "integer", "description": "Cobranças com devolução, total ou parcial." } }, "required": [ "method", "available", "created", "paid", "conversionRate", "paidAmount", "averageTicket", "refundedAmount", "refundRate", "disputedAmount", "disputeRate", "pending", "pendingAmount", "refunded" ] }, "UnavailableRailMetrics": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "PIX", "BOLETO", "CREDITCARD" ], "description": "Meio de pagamento." }, "available": { "type": "boolean", "const": false, "description": "`false`: sem métricas disponíveis para o meio." } }, "required": [ "method", "available" ] }, "AccountMetrics": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Primeiro instante contado." }, "to": { "type": "string", "format": "date-time", "description": "Último instante contado." } }, "required": [ "from", "to" ], "description": "Período efetivamente usado." }, "rails": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/RailMetrics" }, { "$ref": "#/components/schemas/UnavailableRailMetrics" } ] }, "description": "Um item por meio de pagamento da conta. As cobranças contam pela data de criação." }, "withdrawals": { "type": "object", "properties": { "count": { "type": "integer", "description": "Quantidade." }, "amount": { "type": "integer", "description": "Total debitado, com a tarifa. Em centavos." } }, "required": [ "count", "amount" ], "description": "Saques do período que não falharam." }, "deposits": { "type": "object", "properties": { "count": { "type": "integer", "description": "Quantidade." }, "amount": { "type": "integer", "description": "Valor bruto. Em centavos." }, "netAmount": { "type": "integer", "description": "Valor creditado. Em centavos." } }, "required": [ "count", "amount", "netAmount" ], "description": "Pix recebidos sem cobrança, pela data em que caíram." }, "pixInflow": { "type": [ "object", "null" ], "properties": { "count": { "type": "integer", "description": "Quantidade." }, "amount": { "type": "integer", "description": "Valor bruto. Em centavos." } }, "required": [ "count", "amount" ], "description": "Tudo o que entrou por Pix: cobranças pagas e depósitos. `null` quando a conta não tem Pix." } }, "required": [ "period", "rails", "withdrawals", "deposits", "pixInflow" ] }, "Infraction": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador da contestação na PayZu." }, "protocol": { "type": "string", "description": "Protocolo da contestação. É o identificador usado na consulta e nos webhooks." }, "type": { "type": "string", "enum": [ "REFUND_REQUEST", "FRAUD", "REFUND_CANCELLED" ], "description": "Motivo alegado." }, "status": { "type": "string", "enum": [ "OPEN", "ACKNOWLEDGED", "DEFENDED", "ANSWERED", "WAITING_PSP", "WAITING_ADJUSTMENTS", "CANCELLED", "CLOSED" ], "description": "Etapa da contestação. `OPEN`, `CLOSED` e `CANCELLED` movem dinheiro; as demais são etapas entre os bancos. A cancelada devolve o valor bloqueado inteiro, sem taxa de análise." }, "reportedBy": { "type": "string", "enum": [ "DEBITED_PARTICIPANT", "CREDITED_PARTICIPANT" ], "description": "Ponta que abriu a contestação." }, "reportDetails": { "type": "string", "description": "Relato de quem abriu." }, "analysisResult": { "type": [ "string", "null" ], "enum": [ "AGREED", "DISAGREED" ], "description": "Resultado, quando `CLOSED`. `AGREED`: procedente, o valor volta ao pagador. `DISAGREED`: improcedente, o valor volta ao saldo disponível, menos a taxa de análise." }, "analysisDetails": { "type": [ "string", "null" ], "description": "Justificativa do resultado." }, "endToEndId": { "type": "string", "description": "End-to-end do Pix contestado." }, "blockedAmount": { "type": "integer", "description": "Valor separado do saldo disponível enquanto a análise corre. Em centavos." }, "feeCharged": { "type": "integer", "description": "Taxa de análise cobrada. `0` até o encerramento. Em centavos." }, "settledAmount": { "type": "integer", "description": "Quanto voltou ao pagador. `0` até o encerramento. Em centavos." }, "reportedAt": { "type": "string", "format": "date-time", "description": "Quando foi aberta." }, "dueAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Prazo para responder. `null` quando não há." }, "closedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando foi encerrada." }, "origin": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PAYMENT", "DEPOSIT" ], "description": "`PAYMENT`: cobrança. `DEPOSIT`: Pix recebido sem cobrança." }, "id": { "type": "string", "description": "Identificador da cobrança ou do depósito como vem nos webhooks." }, "amount": { "type": "integer", "description": "Valor recebido. Em centavos." }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando foi recebido." }, "payerName": { "type": [ "string", "null" ], "description": "Numa cobrança, o cliente informado; num depósito, o pagador informado pelo banco." }, "payerDocument": { "type": [ "string", "null" ], "description": "CPF mascarado ou CNPJ formatado." } }, "required": [ "kind", "id", "amount", "paidAt", "payerName", "payerDocument" ], "description": "Operação contestada." } }, "required": [ "id", "protocol", "type", "status", "reportedBy", "reportDetails", "analysisResult", "analysisDetails", "endToEndId", "blockedAmount", "feeCharged", "settledAmount", "reportedAt", "dueAt", "closedAt", "origin" ] }, "InfractionList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Infraction" }, "description": "Contestações da conta, pela data de abertura, da mais recente para a mais antiga." }, "nextCursor": { "type": "string", "description": "Cursor da próxima página. Ausente na última página." } }, "required": [ "data" ] }, "CreateWebhook": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "URL HTTPS pública do endpoint. Até 2048 caracteres." }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "PAYMENT_CREATED", "PAYMENT_PAID", "PAYMENT_REFUNDED", "PAYMENT_EXPIRED", "WITHDRAW_CREATED", "WITHDRAW_COMPLETED", "WITHDRAW_FAILED", "INFRACTION_OPENED", "INFRACTION_CLOSED", "INFRACTION_DEADLINE", "DEPOSIT_RECEIVED", "REFUND_COMPLETED", "REFUND_FAILED", "ACCOUNT_BLOCKED", "ACCOUNT_UNBLOCKED", "INTERNAL_TRANSFER_SENT", "INTERNAL_TRANSFER_RECEIVED", "WITHDRAW_REFUND_RECEIVED" ] }, "description": "Eventos que o endpoint recebe. Ao menos um." }, "isActive": { "default": true, "type": "boolean", "description": "Se o endpoint recebe webhooks." } }, "required": [ "url", "events" ] }, "UpdateWebhook": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Nova URL HTTPS pública." }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "PAYMENT_CREATED", "PAYMENT_PAID", "PAYMENT_REFUNDED", "PAYMENT_EXPIRED", "WITHDRAW_CREATED", "WITHDRAW_COMPLETED", "WITHDRAW_FAILED", "INFRACTION_OPENED", "INFRACTION_CLOSED", "INFRACTION_DEADLINE", "DEPOSIT_RECEIVED", "REFUND_COMPLETED", "REFUND_FAILED", "ACCOUNT_BLOCKED", "ACCOUNT_UNBLOCKED", "INTERNAL_TRANSFER_SENT", "INTERNAL_TRANSFER_RECEIVED", "WITHDRAW_REFUND_RECEIVED" ] }, "description": "Nova lista de eventos. Ao menos um." }, "isActive": { "type": "boolean", "description": "`false` para de enviar webhooks ao endpoint na hora." } }, "minProperties": 1 }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do endpoint." }, "url": { "type": "string", "description": "URL do endpoint." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "PAYMENT_CREATED", "PAYMENT_PAID", "PAYMENT_REFUNDED", "PAYMENT_EXPIRED", "WITHDRAW_CREATED", "WITHDRAW_COMPLETED", "WITHDRAW_FAILED", "INFRACTION_OPENED", "INFRACTION_CLOSED", "INFRACTION_DEADLINE", "DEPOSIT_RECEIVED", "REFUND_COMPLETED", "REFUND_FAILED", "ACCOUNT_BLOCKED", "ACCOUNT_UNBLOCKED", "INTERNAL_TRANSFER_SENT", "INTERNAL_TRANSFER_RECEIVED", "WITHDRAW_REFUND_RECEIVED" ] }, "description": "Eventos assinados." }, "isActive": { "type": "boolean", "description": "Se o endpoint recebe webhooks." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora em ISO 8601, UTC." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data e hora em ISO 8601, UTC." } }, "required": [ "id", "url", "events", "isActive", "createdAt", "updatedAt" ] }, "WebhookList": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "WebhookCreated": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Segredo do endpoint, com prefixo `whsec_`. Assina os webhooks e só aparece nesta resposta." } }, "required": [ "secret" ] } ] }, "CallbackSecret": { "type": "object", "properties": { "secret": { "type": "string", "description": "Segredo de callback da conta, com prefixo `cbsec_`. Assina os webhooks enviados à `callbackUrl` e só aparece nesta resposta." } }, "required": [ "secret" ] }, "CallbackSecretStatus": { "type": "object", "properties": { "hasCallbackSecret": { "type": "boolean", "description": "Se a conta já tem segredo de callback." } }, "required": [ "hasCallbackSecret" ] }, "PaymentCreatedEvent": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Identificador da cobrança. Aceito em `GET /transactions/payment/{paymentId}`." }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "REFUNDED", "EXPIRED" ], "description": "`PENDING`." }, "amount": { "type": "integer", "description": "Valor cobrado, em centavos." }, "method": { "type": "string", "enum": [ "PIX" ], "description": "`PIX`." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data de criação, ISO 8601." }, "qrCode": { "type": "string", "description": "Pix copia e cola." }, "metadata": { "type": "object", "additionalProperties": true, "description": "O `metadata` enviado na criação. Só quando enviado e não vazio." }, "externalRef": { "type": "string", "description": "A `externalRef` enviada na criação. Só quando enviada." } }, "required": [ "paymentId", "status", "amount", "method", "createdAt" ] }, "PaymentSettledEvent": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Identificador da cobrança. Aceito em `GET /transactions/payment/{paymentId}`." }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "REFUNDED", "EXPIRED" ], "description": "`PAID` em `PAYMENT_PAID`; `REFUNDED` em `PAYMENT_REFUNDED`." }, "amount": { "type": "integer", "description": "Valor cobrado, em centavos." }, "serviceFee": { "type": "integer", "description": "Tarifa do recebimento, em centavos." }, "netAmount": { "type": "integer", "description": "`amount − serviceFee`: o que foi creditado no recebimento." }, "debitedAmount": { "type": "integer", "description": "Só em `PAYMENT_REFUNDED`: o que saiu da conta, o valor cheio." }, "serviceFeeReturned": { "type": "boolean", "description": "Só em `PAYMENT_REFUNDED`, sempre `false`." }, "endToEndId": { "type": "string", "description": "End-to-end do Pix, quando o banco informa." }, "metadata": { "type": "object", "additionalProperties": true, "description": "O `metadata` enviado na criação. Só quando enviado e não vazio." }, "externalRef": { "type": "string", "description": "A `externalRef` enviada na criação. Só quando enviada." } }, "required": [ "paymentId", "status", "amount", "serviceFee", "netAmount" ] }, "PaymentExpiredEvent": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Identificador da cobrança. Aceito em `GET /transactions/payment/{paymentId}`." }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "REFUNDED", "EXPIRED" ], "description": "`EXPIRED`." }, "amount": { "type": "integer", "description": "Valor cobrado, em centavos." }, "metadata": { "type": "object", "additionalProperties": true, "description": "O `metadata` enviado na criação. Só quando enviado e não vazio." }, "externalRef": { "type": "string", "description": "A `externalRef` enviada na criação. Só quando enviada." } }, "required": [ "paymentId", "status", "amount" ] }, "WithdrawEvent": { "type": "object", "properties": { "withdrawId": { "type": "string", "description": "Identificador do saque. Aceito em `GET /transactions/withdraw/{withdrawId}`." }, "status": { "type": "string", "enum": [ "REQUESTED", "CREATED", "APPROVED", "CONFIRMED", "FAILED" ], "description": "`REQUESTED` em `WITHDRAW_CREATED`, `CONFIRMED` em `WITHDRAW_COMPLETED`, `FAILED` em `WITHDRAW_FAILED`." }, "operation": { "type": "string", "enum": [ "WITHDRAW", "EXTERNAL_PAYMENT" ], "description": "`WITHDRAW` (saque para chave) ou `EXTERNAL_PAYMENT` (pagamento de Pix copia e cola)." }, "amount": { "type": "integer", "description": "O que chega ao destino, em centavos." }, "serviceFee": { "type": "integer", "description": "Tarifa, somada por cima." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`." }, "pixKey": { "type": "string", "description": "Destino. No saque, a chave enviada; no pagamento de Pix copia e cola, mascarada (CPF, e-mail e telefone saem mascarados; CNPJ e chave aleatória, legíveis.)" }, "endToEndId": { "type": "string", "description": "End-to-end do Pix, quando o banco informa." }, "reason": { "type": "string", "description": "Só em `WITHDRAW_FAILED`: mensagem pronta para exibir." } }, "required": [ "withdrawId", "status", "operation", "amount", "serviceFee", "totalDebited", "pixKey" ] }, "RefundEvent": { "type": "object", "properties": { "refundId": { "type": "string", "description": "Identificador do estorno." }, "paymentId": { "type": "string", "description": "Quando o estorno é de uma cobrança." }, "depositId": { "type": "string", "description": "Quando o estorno é de um depósito. Vem um dos dois." }, "status": { "type": "string", "enum": [ "SETTLED", "RELEASED" ], "description": "`SETTLED` (devolvido ao pagador) ou `RELEASED` (recusado, valor de volta ao saldo)." }, "amount": { "type": "integer", "description": "O que volta ao pagador, em centavos." }, "totalDebited": { "type": "integer", "description": "`amount` + tarifa de estorno." }, "endToEndId": { "type": "string", "description": "Só em `REFUND_COMPLETED`: end-to-end do Pix de devolução. Pode não vir." }, "reason": { "type": "string", "description": "Só em `REFUND_FAILED`, quando há: mensagem pronta para exibir." } }, "required": [ "refundId", "status", "amount", "totalDebited" ] }, "DepositReceivedEvent": { "type": "object", "properties": { "depositId": { "type": "string", "description": "Identificador do depósito. Aceito em `GET /transactions/deposit/{depositId}`." }, "amount": { "type": "integer", "description": "Valor recebido, em centavos." }, "serviceFee": { "type": "integer", "description": "Tarifa, em centavos." }, "netAmount": { "type": "integer", "description": "`amount − serviceFee`: o que foi creditado." }, "endToEndId": { "type": "string", "description": "End-to-end do Pix. Sempre vem." }, "payerName": { "type": "string", "description": "Nome do pagador, quando o banco informa." }, "payerDocument": { "type": "string", "description": "CPF ou CNPJ do pagador, como o banco informou." } }, "required": [ "depositId", "amount", "serviceFee", "netAmount", "endToEndId" ] }, "WithdrawRefundReceivedEvent": { "type": "object", "properties": { "depositId": { "type": "string", "description": "Identificador do crédito." }, "withdrawId": { "type": "string", "description": "Saque cujo Pix voltou." }, "amount": { "type": "integer", "description": "Valor devolvido, creditado sem tarifa, em centavos." }, "originalAmount": { "type": "integer", "description": "Valor que tinha saído, em centavos." }, "partial": { "type": "boolean", "description": "`true` quando voltou menos do que saiu." }, "e2e": { "type": "string", "description": "End-to-end da devolução." }, "originalE2e": { "type": "string", "description": "End-to-end do Pix que saiu." }, "returnedAt": { "type": "string", "format": "date-time", "description": "Quando a devolução foi registrada." } }, "required": [ "depositId", "withdrawId", "amount", "originalAmount", "partial", "e2e", "originalE2e", "returnedAt" ] }, "InternalTransferSentEvent": { "type": "object", "properties": { "transferId": { "type": "string", "description": "Identificador da transferência, o mesmo nas duas pontas." }, "status": { "type": "string", "const": "CONFIRMED", "description": "`CONFIRMED`." }, "amount": { "type": "integer", "description": "O que foi para o destino, em centavos." }, "serviceFee": { "type": "integer", "description": "Tarifa, em centavos." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`." }, "toPixKey": { "type": "string", "description": "Chave de destino, mascarada quando é CPF, telefone ou e-mail." } }, "required": [ "transferId", "status", "amount", "serviceFee", "totalDebited", "toPixKey" ] }, "InternalTransferReceivedEvent": { "type": "object", "properties": { "transferId": { "type": "string", "description": "Identificador da transferência, o mesmo nas duas pontas." }, "status": { "type": "string", "const": "CONFIRMED", "description": "`CONFIRMED`." }, "amount": { "type": "integer", "description": "O que entrou, em centavos." }, "fromPixKey": { "type": "string", "description": "Chave da conta que enviou, mascarada quando é CPF, telefone ou e-mail." } }, "required": [ "transferId", "status", "amount", "fromPixKey" ] }, "InfractionEvent": { "type": "object", "properties": { "protocol": { "type": "string", "description": "Protocolo da contestação." }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED", "CANCELLED" ], "description": "`OPEN` na abertura; `CLOSED` ou `CANCELLED` no encerramento." }, "paymentId": { "type": "string", "description": "Quando a contestação é sobre uma cobrança." }, "depositId": { "type": "string", "description": "Quando a contestação é sobre um depósito. Vem um dos dois." }, "amount": { "type": "integer", "description": "Valor da cobrança ou do depósito contestado, em centavos." }, "reportDetails": { "type": "string", "description": "Relato de quem contestou." }, "analysisResult": { "type": "string", "enum": [ "AGREED", "DISAGREED" ], "description": "`AGREED` (procedente) ou `DISAGREED` (improcedente), quando há." }, "dueAt": { "type": "string", "format": "date-time", "description": "Prazo de resposta, quando há." }, "blockedAmount": { "type": "integer", "description": "O que foi separado do saldo, em centavos. Só quando maior que zero." }, "settledAmount": { "type": "integer", "description": "Só em `INFRACTION_CLOSED`: o que voltou ao pagador, em centavos." }, "feeCharged": { "type": "integer", "description": "Só em `INFRACTION_CLOSED`: taxa de análise cobrada, em centavos." } }, "required": [ "protocol", "status", "amount", "reportDetails" ] }, "InfractionDeadlineEvent": { "type": "object", "properties": { "protocol": { "type": "string", "description": "Protocolo da contestação." }, "paymentId": { "type": "string", "description": "Quando a contestação é sobre uma cobrança." }, "depositId": { "type": "string", "description": "Quando a contestação é sobre um depósito." }, "amount": { "type": "integer", "description": "Valor contestado, em centavos." }, "dueAt": { "type": "string", "format": "date-time", "description": "Prazo de resposta." }, "hoursRemaining": { "type": "integer", "description": "`48`, `24` ou `6`: horas que faltam para o prazo." } }, "required": [ "protocol", "amount", "dueAt", "hoursRemaining" ] }, "AccountBlockingEvent": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "SUSPENDED", "ACTIVE" ], "description": "`SUSPENDED` no bloqueio, `ACTIVE` no desbloqueio." }, "blockings": { "type": "array", "items": { "type": "string" }, "description": "Bloqueios em vigor, nos códigos do banco. Vazia no desbloqueio." }, "blockedOperations": { "type": "array", "items": { "type": "string", "enum": [ "PIX_IN", "PIX_OUT", "INTERNAL_TRANSFER_OUT", "INTERNAL_TRANSFER_IN" ] }, "description": "O que a API recusa enquanto a lista vigora: `PIX_IN`, `PIX_OUT`, `INTERNAL_TRANSFER_OUT`, `INTERNAL_TRANSFER_IN`." }, "changedAt": { "type": "string", "format": "date-time", "description": "Quando a mudança foi gravada." } }, "required": [ "status", "blockings", "blockedOperations", "changedAt" ] } } } }