{ "openapi": "3.1.0", "info": { "version": "1.0.0", "title": "PayZu Digital Account API", "description": "PayZu Digital Account API: Pix charges, withdrawals, Pix copy-and-paste payments, transfers between accounts, Pix keys, statement, MED disputes and webhooks.\n\nAmounts in cents, percentages in basis points (`150` = 1.5%), dates in ISO 8601 (UTC). Every operation runs on the credential account.\n\nHow to authenticate: [Authentication](https://docs.payzu.com.br/en/docs/conta-digital/authentication). Guides and full reference at [docs.payzu.com.br/en/docs/conta-digital](https://docs.payzu.com.br/en/docs/conta-digital)." }, "servers": [ { "url": "https://api.hub.payzu.com.br/api/v1", "description": "Production" } ], "tags": [ { "name": "Authentication", "description": "Credential exchange for an access token." }, { "name": "Charges", "description": "Pix charges: create, get, list, receipt and refund." }, { "name": "Withdrawals", "description": "Withdrawals to a Pix key." }, { "name": "Pix", "description": "Pix copy-and-paste decoding and payment, and recipient lookup." }, { "name": "Pix Keys", "description": "Account Pix keys." }, { "name": "Internal Transfers", "description": "Transfers between PayZu accounts." }, { "name": "Deposits", "description": "Pix received without a charge." }, { "name": "Account", "description": "Balance, statement, limits and metrics." }, { "name": "Infractions", "description": "MED disputes opened against the account." }, { "name": "Webhooks", "description": "Webhook endpoints and callback secret." }, { "name": "Status", "description": "Service health." }, { "name": "Webhook Events", "description": "Webhooks PayZu sends to your endpoint, one per event." } ], "paths": { "/oauth/token": { "post": { "summary": "Get access token", "description": "Exchanges the credential for an access token valid for 15 minutes. Send `client_id` and `client_secret` in the `Authorization: Basic` header or in the body, as `application/x-www-form-urlencoded` or JSON. Exchanges are limited per `client_id` and IP, and the credential IP allowlist applies here too.", "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 issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthToken" }, "examples": { "Token issued": { "summary": "Token issued", "value": { "access_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..mQ3Zy1hbVhpbXBsZQ.ZXhlbXBsbw.c2lnbmF0dXJl", "token_type": "Bearer", "expires_in": 900, "scope": "PAYMENT_WRITE PAYMENT_READ STATEMENT_READ" } } } } } }, "400": { "description": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Request limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "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": "Create Pix charge", "description": "Scope: `PAYMENT_WRITE`.\n\nGenerates a charge and returns the Pix copy-and-paste code your customer will pay. The code comes in `pix.qrCodeText`. The charge starts as `PENDING`; the balance changes when the payment is confirmed, and the confirmation arrives through the `PAYMENT_PAID` webhook. Request limit: 60 per minute per credential and 120 per account.", "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": "The `externalRef` already had a charge with the same data; it is returned and nothing is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "Existing charge": { "summary": "Existing charge", "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": "Charge created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "Charge created": { "summary": "Charge created", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Conflict with the current state.", "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": "A step is missing before this operation.", "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": "Business rule refusal.", "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": "Request limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "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": "The bank did not respond or refused.", "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": "Lookup service or rate limiter unavailable; nothing was done.", "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": "List charges", "description": "Scope: `PAYMENT_READ`.\n\nReturns the account charges, newest first, cursor paginated.", "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": "Items per page, 1 to 100." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" }, "description": "`nextCursor` from the previous page." }, { "in": "query", "name": "method", "required": false, "schema": { "type": "string", "enum": [ "PIX" ] }, "description": "Payment method." }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "PAID", "REFUNDED", "EXPIRED" ] }, "description": "Charge status." }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string" }, "description": "Start of the period, by creation date. ISO 8601 or `YYYY-MM-DD`; a date without a time covers the whole day in Brasília time." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string" }, "description": "End of the period, by creation date. ISO 8601 or `YYYY-MM-DD`; a date without a time covers the whole day in Brasília time." }, { "in": "query", "name": "search", "required": false, "schema": { "type": "string", "minLength": 3, "maxLength": 120 }, "description": "Id, name or document of the customer informed on creation. 3 to 120 characters." }, { "in": "query", "name": "externalRef", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "pedido-4821", "description": "Your reference, exact match." } ], "responses": { "200": { "description": "Page of charges.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentList" }, "examples": { "Page of charges": { "summary": "Page of charges", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Get charge", "description": "Scope: `PAYMENT_READ`.\n\nReturns a charge with its Pix copy-and-paste code, the payer and the refunds. Accepts the charge `id` and the webhook `paymentId`.", "operationId": "get_payment", "tags": [ "Charges" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "paymentId", "required": true, "schema": { "type": "string" }, "example": "hubp-20261005K7Q2M9XB4T127431", "description": "Charge identifier." } ], "responses": { "200": { "description": "Charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "Paid charge": { "summary": "Paid charge", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "Charge receipt", "description": "Scope: `PAYMENT_READ`.\n\nReturns the charge receipt as a PDF, base64 encoded. Only for `PAID` or `REFUNDED` charges.", "operationId": "get_payment_receipt", "tags": [ "Charges" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "paymentId", "required": true, "schema": { "type": "string" }, "example": "hubp-20261005K7Q2M9XB4T127431", "description": "Charge identifier." } ], "responses": { "200": { "description": "Receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "examples": { "Receipt": { "summary": "Receipt", "value": { "filename": "comprovante-pix-hubp-20261005K7Q2M9XB4T127431.pdf", "contentType": "application/pdf", "fileBase64": "JVBERi0xLjcKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nCvkMlAwUDC1NNUzMjNSMDEz" } } } } } }, "401": { "description": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "Business rule refusal.", "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": "Refund charge", "description": "Scope: `REFUND`.\n\nReturns all or part of the amount of a paid charge to the payer. Without `amount`, returns the remaining amount; the refund fee is added on top. The amount leaves the available balance when you make the request and returns if the refund fails. One refund at a time per charge; the result arrives through the `REFUND_COMPLETED` or `REFUND_FAILED` webhooks. Counts towards the withdrawal request limit. Does not accept `Idempotency-Key`: on a `502`, get the charge before retrying.", "operationId": "post_payment_refund", "tags": [ "Charges" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "paymentId", "required": true, "schema": { "type": "string" }, "example": "hubp-20261005K7Q2M9XB4T127431", "description": "Charge identifier." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefund" }, "example": { "amount": 1000 } } } }, "responses": { "200": { "description": "The updated charge, with the refund in `refunds`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "Refund on its way": { "summary": "Refund on its way", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "A step is missing before this operation.", "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": "Business rule refusal.", "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": "Request limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "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": "The bank did not respond or refused.", "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": "Lookup service or rate limiter unavailable; nothing was done.", "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": "Withdraw to Pix key", "description": "Scope: `WITHDRAW`.\n\nSends a Pix from the account to a Pix key. `amount` is what reaches the destination; the fee is added on top. The total leaves the available balance when you make the request and returns if the withdrawal fails. A `201` response is not money delivered: confirmation comes through the `WITHDRAW_COMPLETED` webhook and failure through `WITHDRAW_FAILED`. Request limit: 5 per minute per credential and 10 per account, shared with Pix copy-and-paste payments and refunds.", "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": "Unique value per operation, 1 to 255 visible ASCII characters, no spaces. Repeating the key with the same amount and destination returns the original operation; with a different amount or destination, `409`. Scoped to the account, no expiration." } ], "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": "Withdrawal registered. With the same `Idempotency-Key` and data, the existing withdrawal, in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdraw" }, "examples": { "Withdrawal approved by the bank": { "summary": "Withdrawal approved by the bank", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Conflict with the current state.", "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": "A step is missing before this operation.", "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": "Business rule refusal.", "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": "Request limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "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": "The bank did not respond or refused.", "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": "Lookup service or rate limiter unavailable; nothing was done.", "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": "# One new key per operation.\nIDEMPOTENCY_KEY=$(uuidgen)\n\n# On retry, run only the curl below again: it reuses the same key.\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// One new key per operation; on retry, send the same key again.\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# One new key per operation; on retry, send the same key again.\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": "List withdrawals", "description": "Scope: `WITHDRAW_READ`.\n\nReturns the account withdrawals, including Pix copy-and-paste payments, newest first, cursor paginated.", "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": "Items per page, 1 to 100." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" }, "description": "`nextCursor` from the previous page." }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "REQUESTED", "CREATED", "APPROVED", "CONFIRMED", "FAILED" ] }, "description": "Withdrawal status." }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string" }, "description": "Start of the period, by creation date. ISO 8601 or `YYYY-MM-DD`; a date without a time covers the whole day in Brasília time." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string" }, "description": "End of the period, by creation date. ISO 8601 or `YYYY-MM-DD`; a date without a time covers the whole day in Brasília time." } ], "responses": { "200": { "description": "Page of withdrawals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawList" }, "examples": { "Page of withdrawals": { "summary": "Page of withdrawals", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Get withdrawal", "description": "Scope: `WITHDRAW_READ`.\n\nReturns a withdrawal or a Pix copy-and-paste payment, with its current status. Accepts the withdrawal `id` and the webhook `withdrawId`.", "operationId": "get_withdraw", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "withdrawId", "required": true, "schema": { "type": "string" }, "example": "hubp-20261005R4D8TN2WQZ127431", "description": "Withdrawal or Pix copy-and-paste payment identifier." } ], "responses": { "200": { "description": "Withdrawal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawDetail" }, "examples": { "Completed withdrawal": { "summary": "Completed withdrawal", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "Withdrawal receipt", "description": "Scope: `WITHDRAW_READ`.\n\nReturns the withdrawal receipt as a PDF, base64 encoded. Only for `CONFIRMED` withdrawals.", "operationId": "get_withdraw_receipt", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "withdrawId", "required": true, "schema": { "type": "string" }, "example": "hubp-20261005R4D8TN2WQZ127431", "description": "Withdrawal or Pix copy-and-paste payment identifier." } ], "responses": { "200": { "description": "Receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "examples": { "Receipt": { "summary": "Receipt", "value": { "filename": "comprovante-pix-hubp-20261005R4D8TN2WQZ127431.pdf", "contentType": "application/pdf", "fileBase64": "JVBERi0xLjcKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nCvkMlAwUDC1NNUzMjNSMDEz" } } } } } }, "401": { "description": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "Business rule refusal.", "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": "Decode Pix code", "description": "Scope: `PIX_DICT_READ`.\n\nExtracts the data in a Pix copy-and-paste code, such as key and amount, without querying the bank. It does not count towards the request limit, does not identify the holder and does not pay anything. For a dynamic code, `pixKey` is `null` and only `url` is filled.", "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": "Decoded code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecodedQrCode" }, "examples": { "Static code with amount": { "summary": "Static code with amount", "value": { "pixKey": "fulano@exemplo.com", "url": null, "amount": 2500, "merchantName": "FULANO DE TAL", "merchantCity": "SAO PAULO", "txid": "PEDIDO4821", "isDynamic": false, "isAmountFixed": true } } } } } }, "400": { "description": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Look up recipient", "description": "Scope: `PIX_DICT_READ`.\n\nShows the holder and institution of a Pix key or Pix copy-and-paste code, to check before paying. Request limit: 30 lookups per minute per account.", "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": "Recipient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixDestination" }, "examples": { "Recipient": { "summary": "Recipient", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "A step is missing before this operation.", "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": "Business rule refusal.", "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": "Request limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "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": "The bank did not respond or refused.", "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": "Lookup service or rate limiter unavailable; nothing was done.", "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": "Pay Pix code", "description": "Scope: `WITHDRAW`.\n\nPays a Pix copy-and-paste code, static or dynamic, from the account available balance. It works like a withdrawal: same response, limits, daily cap and request limit, with the Pix copy-and-paste payment fee (`externalPayment` in limits). `Idempotency-Key` also compares the paid code. Track it through the `WITHDRAW_*` webhooks and the withdrawal lookup, with `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": "Unique value per operation, 1 to 255 visible ASCII characters, no spaces. Repeating the key with the same amount and destination returns the original operation; with a different amount or destination, `409`. Scoped to the account, no expiration." } ], "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": "Payment registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdraw" }, "examples": { "Payment approved by the bank": { "summary": "Payment approved by the bank", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "Conflict with the current state.", "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": "A step is missing before this operation.", "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": "Business rule refusal.", "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": "Request limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "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": "The bank did not respond or refused.", "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": "Lookup service or rate limiter unavailable; nothing was done.", "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": "# One new key per operation.\nIDEMPOTENCY_KEY=$(uuidgen)\n\n# On retry, run only the curl below again: it reuses the same key.\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// One new key per operation; on retry, send the same key again.\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# One new key per operation; on retry, send the same key again.\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": "List Pix keys", "description": "Scope: `PIX_KEY_READ`.\n\nReturns the account Pix keys, with the default key first. The others come oldest first.", "operationId": "get_pix_keys", "tags": [ "Pix Keys" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Account keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixKeyList" }, "examples": { "Account keys": { "summary": "Account keys", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Create Pix key", "description": "Scope: `PIX_KEY_WRITE`.\n\nRegisters a new Pix key on the account, random (`EVP`) or CNPJ. The key comes back already `ACTIVE`, and the first key of the account becomes the default.", "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": "Key created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixKey" }, "examples": { "Key": { "summary": "Key", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Conflict with the current state.", "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": "A step is missing before this operation.", "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": "Business rule refusal.", "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": "The bank did not respond or refused.", "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": "Set default key", "description": "Scope: `PIX_KEY_WRITE`.\n\nReplaces the account default key with the given key. The default key is the one that receives charges and the one that identifies your account in the transfers you send. To receive a transfer, any `ACTIVE` key works. Only an `ACTIVE` key can become the default.", "operationId": "put_pix_key_default", "tags": [ "Pix Keys" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "pixKeyId", "required": true, "schema": { "type": "string" }, "example": "cmu5k2x0a000301s6ab12cd34", "description": "Key identifier (`id`), not its value." } ], "responses": { "200": { "description": "The key, now default.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixKey" }, "examples": { "Key": { "summary": "Key", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "A step is missing before this operation.", "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": "Business rule refusal.", "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": "The bank did not respond or refused.", "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": "Delete Pix key", "description": "Scope: `PIX_KEY_WRITE`.\n\nRemoves the key from the account and from DICT. The default key cannot be deleted, and an already deleted key returns `404`.", "operationId": "delete_pix_key", "tags": [ "Pix Keys" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "pixKeyId", "required": true, "schema": { "type": "string" }, "example": "cmu5k2x0a000301s6ab12cd34", "description": "Key identifier (`id`), not its value." } ], "responses": { "204": { "description": "No body." }, "401": { "description": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "A step is missing before this operation.", "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": "Business rule refusal.", "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": "The bank did not respond or refused.", "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": "Transfer to another PayZu account", "description": "Scope: `INTERNAL_TRANSFER`.\n\nSends money from your account to another PayZu account, identified by its Pix key. The amount does not go through Pix, and the response already carries the result: `CONFIRMED` means money delivered. The fee is added on top. On a `502` where the bank did not respond or refused temporarily, the transfer stays `REQUESTED` and only the same `Idempotency-Key` returns the original; a definitive refusal leaves the transfer `FAILED`. Request limit: 5 per minute per credential and 10 per account.", "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": "Unique value per operation, 1 to 255 visible ASCII characters, no spaces. Repeating the key with the same amount and destination returns the original operation; with a different amount or destination, `409`. Scoped to the account, no expiration." } ], "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 registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalTransfer" }, "examples": { "Completed transfer": { "summary": "Completed transfer", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "Conflict with the current state.", "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": "A step is missing before this operation.", "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": "Business rule refusal.", "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": "Request limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "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": "The bank did not respond or refused.", "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": "Lookup service or rate limiter unavailable; nothing was done.", "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": "# One new key per operation.\nIDEMPOTENCY_KEY=$(uuidgen)\n\n# On retry, run only the curl below again: it reuses the same key.\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// One new key per operation; on retry, send the same key again.\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# One new key per operation; on retry, send the same key again.\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": "List transfers", "description": "Scope: `INTERNAL_TRANSFER_READ`.\n\nReturns the transfers the account sent and received, newest first, cursor paginated.", "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": "Items per page, 1 to 100." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" }, "description": "`nextCursor` from the previous page." }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "REQUESTED", "CONFIRMED", "FAILED" ] }, "description": "Transfer status." }, { "in": "query", "name": "side", "required": false, "schema": { "type": "string", "enum": [ "SENT", "RECEIVED" ] }, "description": "Only one side: `SENT` or `RECEIVED`. Without it, both are returned." }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string" }, "description": "Start of the period, by creation date. ISO 8601 or `YYYY-MM-DD`; a date without a time covers the whole day in Brasília time." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string" }, "description": "End of the period, by creation date. ISO 8601 or `YYYY-MM-DD`; a date without a time covers the whole day in Brasília time." } ], "responses": { "200": { "description": "Page of transfers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalTransferList" }, "examples": { "Page of transfers": { "summary": "Page of transfers", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Get transfer", "description": "Scope: `INTERNAL_TRANSFER_READ`.\n\nReturns a transfer the account sent or received. Accepts the transfer `id` and the webhook `transferId`.", "operationId": "get_internal_transfer", "tags": [ "Internal Transfers" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "transferId", "required": true, "schema": { "type": "string" }, "example": "hubp-20261005L9C3VH6KMA127431", "description": "Transfer identifier." } ], "responses": { "200": { "description": "Transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalTransfer" }, "examples": { "Completed transfer": { "summary": "Completed transfer", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "Transfer receipt", "description": "Scope: `INTERNAL_TRANSFER_READ`.\n\nReturns the transfer receipt as a PDF, base64 encoded. Only for `CONFIRMED` transfers. It is not a Pix receipt and has no end-to-end ID.", "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": "Transfer identifier." } ], "responses": { "200": { "description": "Receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "examples": { "Receipt": { "summary": "Receipt", "value": { "filename": "comprovante-transferencia-hubp-20261005L9C3VH6KMA127431.pdf", "contentType": "application/pdf", "fileBase64": "JVBERi0xLjcKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nCvkMlAwUDC1NNUzMjNSMDEz" } } } } } }, "401": { "description": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "Business rule refusal.", "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": "Get deposit", "description": "Scope: `DEPOSIT_READ`.\n\nReturns a deposit, which is a Pix received on an account key without a charge. Use the `depositId` from the `DEPOSIT_RECEIVED` webhook.", "operationId": "get_deposit", "tags": [ "Deposits" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "depositId", "required": true, "schema": { "type": "string" }, "example": "cmu4a1b2c000001s6xyz98765", "description": "Deposit identifier." } ], "responses": { "200": { "description": "Deposit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deposit" }, "examples": { "Deposit": { "summary": "Deposit", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "Deposit receipt", "description": "Scope: `DEPOSIT_READ`.\n\nReturns the deposit receipt as a PDF, base64 encoded.", "operationId": "get_deposit_receipt", "tags": [ "Deposits" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "depositId", "required": true, "schema": { "type": "string" }, "example": "cmu4a1b2c000001s6xyz98765", "description": "Deposit identifier." } ], "responses": { "200": { "description": "Receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "examples": { "Receipt": { "summary": "Receipt", "value": { "filename": "comprovante-pix-cmu4a1b2c000001s6xyz98765.pdf", "contentType": "application/pdf", "fileBase64": "JVBERi0xLjcKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nCvkMlAwUDC1NNUzMjNSMDEz" } } } } } }, "401": { "description": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "Return deposit", "description": "Scope: `REFUND`.\n\nReturns all or part of a Pix received without a charge to the payer. Without `amount`, returns the remaining amount; the refund fee is added on top. The amount leaves the available balance when you make the request and returns if the return fails. One return at a time; the result arrives through the `REFUND_COMPLETED` or `REFUND_FAILED` webhooks, with `depositId`.", "operationId": "post_deposit_refund", "tags": [ "Deposits" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "depositId", "required": true, "schema": { "type": "string" }, "example": "cmu4a1b2c000001s6xyz98765", "description": "Deposit identifier." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefund" }, "example": { "amount": 1000 } } } }, "responses": { "200": { "description": "The updated deposit, with the return in `refunds`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deposit" }, "examples": { "Return on its way": { "summary": "Return on its way", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "A step is missing before this operation.", "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": "Business rule refusal.", "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": "Request limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "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": "The bank did not respond or refused.", "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": "Lookup service or rate limiter unavailable; nothing was done.", "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": "Get balance", "description": "Scope: `STATEMENT_READ`.\n\nReturns the account available and blocked balance, with the blocked part broken down by reason.", "operationId": "get_balance", "tags": [ "Account" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "examples": { "Balance": { "summary": "Balance", "value": { "total": 152030, "available": 150530, "blocked": 1500, "blockedBySecurity": 1500, "blockedByWithdraw": 0, "blockedByRefund": 0, "syncedAt": "2026-10-06T18:20:11.004Z" } } } } } }, "401": { "description": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "A step is missing before this operation.", "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": "Get statement", "description": "Scope: `STATEMENT_READ`.\n\nReturns the entries that changed the available balance, cursor paginated. Each line is an entry, not an operation: a paid charge comes in net of the fee, and a withdrawal goes out at request time, for `amount + serviceFee`. Filters are combined.", "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": "Items per page, 1 to 100." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" }, "description": "`nextCursor` from the previous page." }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string" }, "description": "Start of the period, by creation date. ISO 8601 or `YYYY-MM-DD`; a date without a time covers the whole day in Brasília time." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string" }, "description": "End of the period, by creation date. ISO 8601 or `YYYY-MM-DD`; a date without a time covers the whole day in Brasília time." }, { "in": "query", "name": "trigger", "required": false, "schema": { "type": "string" }, "example": "PAYMENT,DEPOSIT", "description": "One or more line types, comma separated: `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": "Charge, withdrawal, deposit or transfer identifier as sent in the webhooks." }, { "in": "query", "name": "amount", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0 }, "description": "Amount in cents, unsigned. Matches incoming and outgoing lines of that amount and also operations with that gross amount." }, { "in": "query", "name": "e2e", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Pix end-to-end ID." }, { "in": "query", "name": "document", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Payer document; punctuation is ignored. On outgoing lines, searches the destination key." }, { "in": "query", "name": "name", "required": false, "schema": { "type": "string", "minLength": 2 }, "description": "At least 2 characters, case insensitive. Payer name on incoming lines, key on outgoing lines." }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELED", "REFUNDED", "WAITING_FOR_REFUND" ] }, "description": "State of the originating operation, not the line `status`. `PENDING`: charge awaiting payment or withdrawal still being processed. `COMPLETED`: paid charge, paid withdrawal or received Pix. `CANCELED`: expired charge or refused withdrawal. `REFUNDED`: charge with a completed refund. `WAITING_FOR_REFUND`: charge with a refund still being processed. Returns the lines of those operations; transfer and dispute lines are left out." }, { "in": "query", "name": "sortBy", "required": false, "schema": { "default": "createdAt", "type": "string", "enum": [ "postedAt", "createdAt" ] }, "description": "Sort field." }, { "in": "query", "name": "sortDirection", "required": false, "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "description": "Sort direction." } ], "responses": { "200": { "description": "Page of the statement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Statement" }, "examples": { "Page of the statement": { "summary": "Page of the statement", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Get limits and fees", "description": "Scope: `STATEMENT_READ`.\n\nReturns the per-operation limits, the fees and the daily caps that apply to the account today. Amounts in cents and percentages in basis points.", "operationId": "get_limits", "tags": [ "Account" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Limits and fees.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountLimits" }, "examples": { "Limits and fees": { "summary": "Limits and fees", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Get metrics", "description": "Scope: `STATEMENT_READ`.\n\nReturns the account figures for the period: charges, conversion, refunds, disputes, withdrawals and deposits.", "operationId": "get_metrics", "tags": [ "Account" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "query", "name": "dateFrom", "required": false, "schema": { "type": "string" }, "example": "2026-09-01", "description": "Start of the period. Without `dateFrom` and `dateTo`, the last 30 days are used." }, { "in": "query", "name": "dateTo", "required": false, "schema": { "type": "string" }, "example": "2026-09-30", "description": "End of the period. ISO 8601 or `YYYY-MM-DD`." } ], "responses": { "200": { "description": "Period metrics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountMetrics" }, "examples": { "September metrics": { "summary": "September metrics", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "List MED disputes", "description": "Scope: `INFRACTION_READ`.\n\nReturns the account MED disputes, newest first by opening date, cursor paginated. Responding to a dispute is done in the dashboard.", "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": "Items per page, 1 to 100." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" }, "description": "`nextCursor` from the previous page." }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "OPEN", "ACKNOWLEDGED", "DEFENDED", "ANSWERED", "WAITING_PSP", "WAITING_ADJUSTMENTS", "CANCELLED", "CLOSED" ] }, "description": "An exact status. With `status`, `open` is ignored." }, { "in": "query", "name": "open", "required": false, "schema": { "type": "boolean" }, "description": "`true` returns only open disputes: every status other than `CLOSED` and `CANCELLED`." }, { "in": "query", "name": "type", "required": false, "schema": { "type": "string", "enum": [ "REFUND_REQUEST", "FRAUD", "REFUND_CANCELLED" ] }, "description": "Alleged reason." }, { "in": "query", "name": "analysisResult", "required": false, "schema": { "type": "string", "enum": [ "AGREED", "DISAGREED" ] }, "description": "Analysis result." } ], "responses": { "200": { "description": "Page of disputes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfractionList" }, "examples": { "Page of disputes": { "summary": "Page of disputes", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Get MED dispute", "description": "Scope: `INFRACTION_READ`.\n\nReturns a MED dispute, with its stage, the blocked amount and the result. Use the `protocol` from the `INFRACTION_OPENED` webhook.", "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": "Dispute protocol." } ], "responses": { "200": { "description": "Dispute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Infraction" }, "examples": { "Open dispute": { "summary": "Open dispute", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "List webhook endpoints", "description": "Scope: `WEBHOOK_READ`.\n\nReturns the endpoints registered on the account, oldest first. The secret is not returned.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Register webhook endpoint", "description": "Scope: `WEBHOOK_WRITE`.\n\nRegisters a URL to receive the webhooks of the chosen events. The response carries the secret that signs the webhooks, and it only appears there.", "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 registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" }, "examples": { "Endpoint registered": { "summary": "Endpoint registered", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Conflict with the current state.", "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": "Business rule refusal.", "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": "Update webhook endpoint", "description": "Scope: `WEBHOOK_WRITE`.\n\nChanges the URL or the events of an endpoint, or deactivates and reactivates it. Send at least one field.", "operationId": "put_webhook", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "webhookId", "required": true, "schema": { "type": "string" }, "example": "cmu6w1h0k000101s6ef34gh56", "description": "Endpoint identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhook" }, "example": { "isActive": false } } } }, "responses": { "200": { "description": "Endpoint updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "examples": { "Deactivated endpoint": { "summary": "Deactivated endpoint", "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": "Invalid request.", "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": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "Conflict with the current state.", "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": "Business rule refusal.", "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": "Delete webhook endpoint", "description": "Scope: `WEBHOOK_WRITE`.\n\nRemoves from the account an endpoint with no recorded delivery yet. With a recorded delivery, the deletion is refused; in that case, deactivate it with `isActive: false`.", "operationId": "delete_webhook", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "parameters": [ { "in": "path", "name": "webhookId", "required": true, "schema": { "type": "string" }, "example": "cmu6w1h0k000101s6ef34gh56", "description": "Endpoint identifier." } ], "responses": { "204": { "description": "No body." }, "401": { "description": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Not found, or from another account.", "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": "Conflict with the current state.", "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": "Business rule refusal.", "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": "Get callback secret status", "description": "Scope: `WEBHOOK_READ`.\n\nTells whether the account already has a callback secret. The value is not returned.", "operationId": "get_callback_secret", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "Secret status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackSecretStatus" }, "examples": { "Secret issued": { "summary": "Secret issued", "value": { "hasCallbackSecret": true } } } } } }, "401": { "description": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Issue callback secret", "description": "Scope: `WEBHOOK_WRITE`.\n\nGenerates the account callback secret, which signs the webhooks sent to the operations `callbackUrl`. Without it, an operation with `callbackUrl` is refused. If the account already has a secret, returns `409`.", "operationId": "post_callback_secret", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "201": { "description": "Secret issued. It only appears in this response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackSecret" }, "examples": { "Secret": { "summary": "Secret", "value": { "secret": "cbsec_2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" } } } } } }, "401": { "description": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Conflict with the current state.", "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": "Rotate callback secret", "description": "Scope: `WEBHOOK_WRITE`.\n\nGenerates a new callback secret. The previous one stops working immediately.", "operationId": "post_callback_secret_rotate", "tags": [ "Webhooks" ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "responses": { "200": { "description": "New secret. It only appears in this response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackSecret" }, "examples": { "Secret": { "summary": "Secret", "value": { "secret": "cbsec_2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" } } } } } }, "401": { "description": "Missing, invalid or expired credential.", "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": "Not allowed: scope, IP or disabled operation.", "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": "Service health", "description": "Tells whether the API is up. No credential required. Returns `500` when the service is unhealthy.", "operationId": "get_status", "tags": [ "Status" ], "security": [], "responses": { "200": { "description": "Service up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" }, "examples": { "Service up": { "summary": "Service up", "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": "Charge registered at the bank.", "operationId": "webhook_payment_created", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "PAYMENT_CREATED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "PAYMENT_CREATED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/PaymentCreatedEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "PAYMENT_PAID": { "post": { "summary": "PAYMENT_PAID", "description": "Charge paid.", "operationId": "webhook_payment_paid", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "PAYMENT_PAID" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "PAYMENT_PAID", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/PaymentSettledEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "PAYMENT_REFUNDED": { "post": { "summary": "PAYMENT_REFUNDED", "description": "The bank returned the payment to the payer without your request. The full amount leaves the account.", "operationId": "webhook_payment_refunded", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "PAYMENT_REFUNDED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "PAYMENT_REFUNDED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/PaymentSettledEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "PAYMENT_EXPIRED": { "post": { "summary": "PAYMENT_EXPIRED", "description": "The charge expired unpaid.", "operationId": "webhook_payment_expired", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "PAYMENT_EXPIRED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "PAYMENT_EXPIRED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/PaymentExpiredEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "WITHDRAW_CREATED": { "post": { "summary": "WITHDRAW_CREATED", "description": "Withdrawal requested; the amount has already left the available balance.", "operationId": "webhook_withdraw_created", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "WITHDRAW_CREATED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "WITHDRAW_CREATED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/WithdrawEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "WITHDRAW_COMPLETED": { "post": { "summary": "WITHDRAW_COMPLETED", "description": "The money reached the destination.", "operationId": "webhook_withdraw_completed", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "WITHDRAW_COMPLETED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "WITHDRAW_COMPLETED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/WithdrawEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "WITHDRAW_FAILED": { "post": { "summary": "WITHDRAW_FAILED", "description": "The withdrawal failed and the amount returned to the balance.", "operationId": "webhook_withdraw_failed", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "WITHDRAW_FAILED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "WITHDRAW_FAILED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/WithdrawEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "REFUND_COMPLETED": { "post": { "summary": "REFUND_COMPLETED", "description": "Refund completed: the amount returned to the payer.", "operationId": "webhook_refund_completed", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "REFUND_COMPLETED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "REFUND_COMPLETED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/RefundEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "REFUND_FAILED": { "post": { "summary": "REFUND_FAILED", "description": "Refund refused: the amount returned to the balance.", "operationId": "webhook_refund_failed", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "REFUND_FAILED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "REFUND_FAILED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/RefundEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "DEPOSIT_RECEIVED": { "post": { "summary": "DEPOSIT_RECEIVED", "description": "Pix received on an account key without a charge.", "operationId": "webhook_deposit_received", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "DEPOSIT_RECEIVED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "DEPOSIT_RECEIVED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/DepositReceivedEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "INTERNAL_TRANSFER_SENT": { "post": { "summary": "INTERNAL_TRANSFER_SENT", "description": "The account sent a transfer.", "operationId": "webhook_internal_transfer_sent", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "INTERNAL_TRANSFER_SENT" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "INTERNAL_TRANSFER_SENT", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/InternalTransferSentEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "INTERNAL_TRANSFER_RECEIVED": { "post": { "summary": "INTERNAL_TRANSFER_RECEIVED", "description": "The account received a transfer.", "operationId": "webhook_internal_transfer_received", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "INTERNAL_TRANSFER_RECEIVED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "INTERNAL_TRANSFER_RECEIVED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/InternalTransferReceivedEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "WITHDRAW_REFUND_RECEIVED": { "post": { "summary": "WITHDRAW_REFUND_RECEIVED", "description": "Whoever received a Pix from the account returned the amount, fully or partially.", "operationId": "webhook_withdraw_refund_received", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "WITHDRAW_REFUND_RECEIVED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "WITHDRAW_REFUND_RECEIVED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/WithdrawRefundReceivedEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "INFRACTION_OPENED": { "post": { "summary": "INFRACTION_OPENED", "description": "MED dispute opened against the account.", "operationId": "webhook_infraction_opened", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "INFRACTION_OPENED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "INFRACTION_OPENED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/InfractionEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "INFRACTION_CLOSED": { "post": { "summary": "INFRACTION_CLOSED", "description": "Dispute closed or cancelled.", "operationId": "webhook_infraction_closed", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "INFRACTION_CLOSED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "INFRACTION_CLOSED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/InfractionEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "INFRACTION_DEADLINE": { "post": { "summary": "INFRACTION_DEADLINE", "description": "The dispute response deadline is approaching: 48, 24 or 6 hours left.", "operationId": "webhook_infraction_deadline", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "INFRACTION_DEADLINE" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "INFRACTION_DEADLINE", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/InfractionDeadlineEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "ACCOUNT_BLOCKED": { "post": { "summary": "ACCOUNT_BLOCKED", "description": "The bank blocked account operations, or the block list changed.", "operationId": "webhook_account_blocked", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "ACCOUNT_BLOCKED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "ACCOUNT_BLOCKED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/AccountBlockingEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } }, "ACCOUNT_UNBLOCKED": { "post": { "summary": "ACCOUNT_UNBLOCKED", "description": "The account blocks were lifted.", "operationId": "webhook_account_unblocked", "tags": [ "Webhook Events" ], "parameters": [ { "in": "header", "name": "X-Payzu-Event", "required": true, "schema": { "type": "string" }, "description": "Event.", "example": "ACCOUNT_UNBLOCKED" }, { "in": "header", "name": "X-Payzu-Delivery", "required": true, "schema": { "type": "string" }, "description": "Delivery identifier. The same on every attempt and on resend: use it to discard repeated deliveries." }, { "in": "header", "name": "X-Payzu-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Time of this attempt, in milliseconds (Unix). Part of the signature." }, { "in": "header", "name": "X-Payzu-Signature", "required": true, "schema": { "type": "string" }, "description": "`sha256=` followed by the HMAC-SHA256, in hex, of `.`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "ACCOUNT_UNBLOCKED", "description": "Event. The same as `X-Payzu-Event`." }, "id": { "type": "string", "description": "Delivery identifier, the same as `X-Payzu-Delivery`. The same on every attempt and on resend." }, "sentAt": { "type": "string", "format": "date-time", "description": "Time of the first attempt. It does not change on later attempts." }, "accountId": { "type": "string", "description": "Account that produced the event." }, "data": { "$ref": "#/components/schemas/AccountBlockingEvent", "description": "Event body." } }, "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": "Any `2xx` within 10 seconds confirms the delivery." } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Token from `POST /oauth/token` (15 minutes) or the credential token `pzu__`." }, "BasicAuth": { "type": "http", "scheme": "basic", "description": "Credential `client_id` and `client_secret`." } }, "schemas": { "Error": { "type": "object", "properties": { "message": { "type": "string", "description": "Description in Portuguese, ready to display. It may change at any time." }, "code": { "type": "string", "description": "Stable error code. Your system decides what to do based on it." }, "details": { "type": "object", "additionalProperties": true, "description": "Structured error context, when available." } }, "required": [ "message", "code" ] }, "OAuthTokenRequest": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "Always `client_credentials`." }, "client_id": { "type": "string", "description": "Credential `client_id`, when it does not go in the `Authorization: Basic` header." }, "client_secret": { "type": "string", "description": "Credential `client_secret`, when it does not go in the `Authorization: Basic` header." } }, "required": [ "grant_type" ] }, "OAuthToken": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Access token. Goes in the `Authorization: Bearer` header of the other routes." }, "token_type": { "type": "string", "enum": [ "Bearer" ], "description": "Always `Bearer`." }, "expires_in": { "type": "integer", "description": "Token lifetime, in seconds." }, "scope": { "type": "string", "description": "Credential scopes, separated by spaces." } }, "required": [ "access_token", "token_type", "expires_in", "scope" ] }, "Status": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "`ok` when the service is up." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time of the response." } }, "required": [ "status", "updated_at" ] }, "CreatePayment": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Charge amount, positive integer. `1500` = R$ 15.00. In cents." }, "method": { "type": "string", "enum": [ "PIX" ], "description": "Payment method. Only `PIX` today." }, "description": { "type": [ "string", "null" ], "maxLength": 140, "description": "Text shown to the payer." }, "externalRef": { "type": [ "string", "null" ], "maxLength": 64, "description": "Your reference for the charge, unique in the account. Repeating it with the same data returns the existing charge with `200`; with different data, `409`." }, "customer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Payer name." }, "document": { "type": "string", "minLength": 11, "description": "CPF or CNPJ, with or without punctuation. The check digit is validated." }, "email": { "type": [ "string", "null" ], "maxLength": 120, "format": "email", "description": "Payer email." }, "phone": { "type": [ "string", "null" ], "maxLength": 20, "description": "Payer phone." } }, "required": [ "name", "document" ], "description": "Who is going to pay." }, "ipAddress": { "type": [ "string", "null" ], "description": "IP address of the buyer in your store. Stored for fraud analysis and disputes; it is not returned in responses or webhooks." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Free-form object returned as sent in the `PAYMENT_*` webhooks of this charge. Up to 20 keys and 4 KB." }, "callbackUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTPS URL that receives every webhook of this operation, in addition to the registered endpoints. Up to 2048 characters. Requires the account callback secret." } }, "required": [ "amount", "method", "customer" ] }, "RefundAttempt": { "type": "object", "properties": { "id": { "type": "string", "description": "Refund identifier. It is the `refundId` in the `REFUND_COMPLETED` and `REFUND_FAILED` webhooks." }, "status": { "type": "string", "enum": [ "RESERVED", "SENT", "SETTLED", "RELEASED" ], "description": "`RESERVED`: the amount left the available balance. `SENT`: sent to the bank. `SETTLED`: returned to the payer. `RELEASED`: refused, with the amount back in the balance." }, "amount": { "type": "integer", "description": "Amount returned to the payer. In cents." }, "serviceFee": { "type": "integer", "description": "Refund fee. In cents." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`: what leaves the account. In cents." }, "endToEndId": { "type": [ "string", "null" ], "description": "End-to-end ID of the return Pix. `null` until it completes." }, "rejectedReason": { "type": [ "string", "null" ], "description": "Message ready to display, set when the bank refused the refund." }, "requestedAt": { "type": "string", "format": "date-time", "description": "When the refund was requested. ISO 8601, UTC." }, "settledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the refund completed. `null` until it completes." }, "releasedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the amount returned to the balance after a refusal. `null` if there was no refusal." } }, "required": [ "id", "status", "amount", "serviceFee", "totalDebited", "endToEndId", "rejectedReason", "requestedAt", "settledAt", "releasedAt" ] }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "description": "Charge identifier. The lookup accepts this `id` and the webhook `paymentId`." }, "method": { "type": "string", "enum": [ "PIX" ], "description": "Payment method." }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "REFUNDED", "EXPIRED" ], "description": "`PENDING`: awaiting payment. `PAID`: paid. `REFUNDED`: fully refunded. `EXPIRED`: expired unpaid." }, "amount": { "type": "integer", "description": "Amount charged. In cents." }, "description": { "type": [ "string", "null" ], "description": "Text shown to the payer." }, "serviceFee": { "type": "integer", "description": "Receiving fee, deducted from the amount. In cents." }, "netAmount": { "type": "integer", "description": "`amount − serviceFee`: what is credited to the account. In cents." }, "refundedAmount": { "type": "integer", "description": "How much has been returned to the payer, completed refunds only. In cents." }, "refundFee": { "type": "integer", "description": "Fee charged on completed refunds. In cents." }, "refundInProgressAmount": { "type": "integer", "description": "Refund requested and still being processed. In cents." }, "refundableAmount": { "type": "integer", "description": "How much can still be refunded. `0` while the charge is unpaid, while a refund is still being processed and while a MED dispute is open. In cents." }, "openInfractionProtocol": { "type": [ "string", "null" ], "description": "Protocol of the open MED dispute on the charge. `null` when there is none." }, "externalRef": { "type": [ "string", "null" ], "description": "Your reference, as sent." }, "callbackUrl": { "type": [ "string", "null" ], "description": "The `callbackUrl` sent on creation. `null` when none was sent." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time in ISO 8601, UTC." }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was paid. `null` until paid." }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was fully refunded. `null` until then." }, "pix": { "type": [ "object", "null" ], "properties": { "qrCodeText": { "type": [ "string", "null" ], "description": "Pix copy-and-paste code (BR Code). The QR Code is drawn from this text." }, "qrCodeUrl": { "type": [ "string", "null" ], "description": "Always `null`." }, "qrCodeBase64": { "type": [ "string", "null" ], "description": "Always `null`." }, "conciliationId": { "type": [ "string", "null" ], "description": "End-to-end ID of the Pix that paid. `null` until paid." } }, "required": [ "qrCodeText", "qrCodeUrl", "qrCodeBase64", "conciliationId" ], "description": "Pix data of the charge." }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "description": "Name informed." }, "document": { "type": "string", "description": "Document informed, digits only." }, "email": { "type": [ "string", "null" ], "description": "Email informed." }, "phone": { "type": [ "string", "null" ], "description": "Phone informed." } }, "required": [ "name", "document", "email", "phone" ], "description": "Payer as informed on creation." }, "payer": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of who paid." }, "document": { "type": [ "string", "null" ], "description": "Masked CPF (`***.982.247-**`) or formatted CNPJ." }, "bankName": { "type": [ "string", "null" ], "description": "Institution of who paid." } }, "required": [ "name", "document", "bankName" ], "description": "Who actually paid, as reported by the bank. `null` until paid." }, "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/RefundAttempt" }, "description": "Refunds of the charge, newest first." } }, "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": "Charge identifier." }, "method": { "type": "string", "enum": [ "PIX" ], "description": "Payment method." }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "REFUNDED", "EXPIRED" ], "description": "Charge status." }, "amount": { "type": "integer", "description": "Amount charged. In cents." }, "netAmount": { "type": "integer", "description": "What is credited to the account, net of the fee. In cents." }, "refundedAmount": { "type": "integer", "description": "How much has been returned to the payer, completed refunds only. In cents." }, "refundInProgressAmount": { "type": "integer", "description": "Refund still being processed. In cents." }, "description": { "type": [ "string", "null" ], "description": "Text shown to the payer." }, "payerName": { "type": [ "string", "null" ], "description": "Payer name informed on creation." }, "payerDocument": { "type": [ "string", "null" ], "description": "Payer document informed on creation, digits only." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time in ISO 8601, UTC." }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was paid. `null` until paid." } }, "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": "Account charges, newest first." }, "nextCursor": { "type": "string", "description": "Cursor for the next page. Absent on the last page." } }, "required": [ "data" ] }, "CreateRefund": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount to return. Without it, returns the remaining amount. In cents." } } }, "Receipt": { "type": "object", "properties": { "filename": { "type": "string", "description": "File name." }, "contentType": { "type": "string", "enum": [ "application/pdf" ], "description": "Always `application/pdf`." }, "fileBase64": { "type": "string", "description": "Receipt PDF, base64 encoded." } }, "required": [ "filename", "contentType", "fileBase64" ] }, "CreateWithdraw": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "description": "Amount that reaches the destination. The fee is added on top. In cents." }, "pixKey": { "type": "string", "minLength": 1, "maxLength": 77, "description": "Destination Pix key." }, "pixKeyType": { "type": "string", "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Key type. Checked against the key; without it, the type is inferred from the format, and 11 digits can be a CPF or a mobile number." }, "comment": { "type": "string", "maxLength": 140, "description": "Text sent to the recipient, when their bank displays it." }, "callbackUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTPS URL that receives every webhook of this operation, in addition to the registered endpoints. Up to 2048 characters. Requires the account callback secret." } }, "required": [ "amount", "pixKey" ] }, "Withdraw": { "type": "object", "properties": { "id": { "type": "string", "description": "Withdrawal identifier. The lookup accepts this `id` and the webhook `withdrawId`." }, "status": { "type": "string", "enum": [ "REQUESTED", "CREATED", "APPROVED", "CONFIRMED", "FAILED" ], "description": "`REQUESTED`: requested; the amount has already left the available balance. `CREATED`: registered at the bank. `APPROVED`: approved, on its way. `CONFIRMED`: the money arrived. `FAILED`: it did not go out, and the amount returned to the balance; it can come from `REQUESTED`, `CREATED` or `APPROVED`." }, "amount": { "type": "integer", "description": "Amount that reaches the destination. In cents." }, "serviceFee": { "type": "integer", "description": "Fee, added on top. In cents." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`: what leaves the account. In cents." }, "pixKey": { "type": "string", "description": "Destination key. For a withdrawal, the key sent, normalized; for a Pix copy-and-paste payment, masked (CPF, email and phone keys are masked; CNPJ and random keys are shown in full.)" }, "comment": { "type": [ "string", "null" ], "description": "Text sent to the recipient." }, "e2e": { "type": [ "string", "null" ], "description": "End-to-end ID of the Pix. `null` until the bank registers it." }, "providerRejectedReason": { "type": [ "string", "null" ], "description": "Message ready to display, set when the bank refused." }, "callbackUrl": { "type": [ "string", "null" ], "description": "The `callbackUrl` sent on creation. `null` when none was sent." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time in ISO 8601, UTC." }, "sentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the bank registered the withdrawal." }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the bank approved the withdrawal." }, "confirmedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the money reached the destination." } }, "required": [ "id", "status", "amount", "serviceFee", "totalDebited", "pixKey", "comment", "e2e", "providerRejectedReason", "callbackUrl", "createdAt", "sentAt", "approvedAt", "confirmedAt" ] }, "WithdrawDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Withdrawal identifier. The lookup accepts this `id` and the webhook `withdrawId`." }, "status": { "type": "string", "enum": [ "REQUESTED", "CREATED", "APPROVED", "CONFIRMED", "FAILED" ], "description": "`REQUESTED`: requested; the amount has already left the available balance. `CREATED`: registered at the bank. `APPROVED`: approved, on its way. `CONFIRMED`: the money arrived. `FAILED`: it did not go out, and the amount returned to the balance; it can come from `REQUESTED`, `CREATED` or `APPROVED`." }, "operation": { "type": "string", "enum": [ "WITHDRAW", "EXTERNAL_PAYMENT" ], "description": "`WITHDRAW`: withdrawal to a key. `EXTERNAL_PAYMENT`: Pix copy-and-paste payment." }, "amount": { "type": "integer", "description": "Amount that reaches the destination. In cents." }, "serviceFee": { "type": "integer", "description": "Fee, added on top. In cents." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`: what leaves the account. In cents." }, "destination": { "type": "object", "properties": { "pixKey": { "type": "string", "description": "Destination key, masked: CPF, email and phone keys are masked; CNPJ and random keys are shown in full." }, "pixKeyType": { "type": [ "string", "null" ], "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Key type, inferred from the format." } }, "required": [ "pixKey", "pixKeyType" ], "description": "Withdrawal destination." }, "comment": { "type": [ "string", "null" ], "description": "Text sent to the recipient." }, "e2e": { "type": [ "string", "null" ], "description": "End-to-end ID of the Pix. `null` until the bank registers it." }, "providerRejectedReason": { "type": [ "string", "null" ], "description": "Message ready to display, set when the bank refused." }, "callbackUrl": { "type": [ "string", "null" ], "description": "The `callbackUrl` sent on creation. `null` when none was sent." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time in ISO 8601, UTC." }, "sentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the bank registered the withdrawal." }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the bank approved the withdrawal." }, "confirmedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the money reached the destination." }, "failedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the withdrawal failed. `null` if it did not fail." } }, "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": "Withdrawal identifier. The lookup accepts this `id` and the webhook `withdrawId`." }, "status": { "type": "string", "enum": [ "REQUESTED", "CREATED", "APPROVED", "CONFIRMED", "FAILED" ], "description": "`REQUESTED`: requested; the amount has already left the available balance. `CREATED`: registered at the bank. `APPROVED`: approved, on its way. `CONFIRMED`: the money arrived. `FAILED`: it did not go out, and the amount returned to the balance; it can come from `REQUESTED`, `CREATED` or `APPROVED`." }, "operation": { "type": "string", "enum": [ "WITHDRAW", "EXTERNAL_PAYMENT" ], "description": "`WITHDRAW`: withdrawal to a key. `EXTERNAL_PAYMENT`: Pix copy-and-paste payment." }, "amount": { "type": "integer", "description": "Amount that reaches the destination. In cents." }, "serviceFee": { "type": "integer", "description": "Fee, added on top. In cents." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`: what leaves the account. In cents." }, "destination": { "type": "object", "properties": { "pixKey": { "type": "string", "description": "Destination key, masked: CPF, email and phone keys are masked; CNPJ and random keys are shown in full." }, "pixKeyType": { "type": [ "string", "null" ], "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Key type, inferred from the format." } }, "required": [ "pixKey", "pixKeyType" ], "description": "Withdrawal destination." }, "comment": { "type": [ "string", "null" ], "description": "Text sent to the recipient." }, "e2e": { "type": [ "string", "null" ], "description": "End-to-end ID of the Pix. `null` until the bank registers it." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time in ISO 8601, UTC." }, "confirmedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the money reached the destination." } }, "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": "Withdrawals and Pix copy-and-paste payments of the account, newest first." }, "nextCursor": { "type": "string", "description": "Cursor for the next page. Absent on the last page." } }, "required": [ "data" ] }, "PayQrCode": { "type": "object", "properties": { "brCode": { "type": "string", "minLength": 8, "maxLength": 1024, "description": "Full Pix copy-and-paste code, as read." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount to pay, when the code has no amount. If it has one, it must match the code. In cents." }, "comment": { "type": "string", "maxLength": 140, "description": "Text sent to the recipient. Without it, the recipient name in the code is used." }, "callbackUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTPS URL that receives every webhook of this operation, in addition to the registered endpoints. Up to 2048 characters. Requires the account callback secret." } }, "required": [ "brCode" ] }, "DecodeQrCode": { "type": "object", "properties": { "brCode": { "type": "string", "minLength": 8, "maxLength": 1024, "description": "Pix copy-and-paste code." } }, "required": [ "brCode" ] }, "DecodedQrCode": { "type": "object", "properties": { "pixKey": { "type": [ "string", "null" ], "description": "Pix key carried by the code, in full. `null` for a dynamic code." }, "url": { "type": [ "string", "null" ], "description": "URL with the data of a dynamic code. `null` for a static code." }, "amount": { "type": [ "integer", "null" ], "description": "Amount fixed in the code. `null` when the payer chooses. In cents." }, "merchantName": { "type": [ "string", "null" ], "description": "Name written by whoever generated the code. Not verified." }, "merchantCity": { "type": [ "string", "null" ], "description": "City written by whoever generated the code. Not verified." }, "txid": { "type": [ "string", "null" ], "description": "Identifier the recipient put in the code." }, "isDynamic": { "type": "boolean", "description": "`true` when the code is single use." }, "isAmountFixed": { "type": "boolean", "description": "`true` when `amount` is not `null`." } }, "required": [ "pixKey", "url", "amount", "merchantName", "merchantCity", "txid", "isDynamic", "isAmountFixed" ] }, "PixDestinationRequest": { "type": "object", "properties": { "pixKey": { "type": "string", "minLength": 1, "maxLength": 140, "description": "Pix key to look up. Send `pixKey` or `brCode`, never both." }, "pixKeyType": { "type": "string", "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Key type. Only with `pixKey`." }, "brCode": { "type": "string", "minLength": 8, "maxLength": 1024, "description": "Pix copy-and-paste code to look up." } } }, "PixDestination": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "PIX_KEY", "BR_CODE" ], "description": "What was looked up: `PIX_KEY` or `BR_CODE`." }, "pixKey": { "type": "string", "description": "Destination key. CPF, email and phone keys are masked; CNPJ and random keys are shown in full." }, "pixKeyType": { "type": [ "string", "null" ], "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Key type, inferred from the format. `null` when the format is not recognized." }, "holder": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Holder full name." }, "document": { "type": [ "string", "null" ], "description": "Masked CPF or formatted CNPJ." } }, "required": [ "name", "document" ], "description": "Key holder. `null` when there is no name or document." }, "bank": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Institution name." }, "ispb": { "type": [ "string", "null" ], "description": "Institution ISPB." }, "branch": { "type": [ "string", "null" ], "description": "Branch." }, "accountNumber": { "type": [ "string", "null" ], "description": "Masked account, with the last four digits visible." } }, "required": [ "name", "ispb", "branch", "accountNumber" ], "description": "Destination institution. `null` when the lookup did not happen." }, "amount": { "type": [ "integer", "null" ], "description": "Amount fixed in the Pix copy-and-paste code. Always `null` for a key. In cents." }, "isAmountFixed": { "type": "boolean", "description": "`true` when `amount` is not `null`." }, "isVerified": { "type": "boolean", "description": "`true` when the name came from DICT; `false` when it came from the Pix copy-and-paste code itself." } }, "required": [ "source", "pixKey", "pixKeyType", "holder", "bank", "amount", "isAmountFixed", "isVerified" ] }, "CreatePixKey": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Key type. Today you can create `EVP` and `CNPJ`." }, "key": { "type": "string", "minLength": 1, "description": "Key value. Required, except for `EVP`, where it must not be sent. CPF and CNPJ must belong to the account holder." } }, "required": [ "type" ] }, "PixKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Key identifier. It goes in the delete and set-default routes." }, "key": { "type": "string", "description": "Key value, in full." }, "type": { "type": "string", "enum": [ "EVP", "CNPJ", "CPF", "EMAIL", "PHONE" ], "description": "Key type." }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "REMOVED" ], "description": "Key status." }, "isDefault": { "type": "boolean", "description": "Whether it is the account default key." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time in ISO 8601, UTC." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time in 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": "Amount that reaches the destination. The fee is added on top. In cents." }, "toPixKey": { "type": "string", "minLength": 1, "maxLength": 77, "description": "Pix key of another PayZu account." }, "comment": { "type": "string", "maxLength": 140, "description": "Text shown on the receipt." }, "callbackUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTPS URL that receives every webhook of this operation, in addition to the registered endpoints. Up to 2048 characters. Requires the account callback secret. The `INTERNAL_TRANSFER_RECEIVED` webhook, which belongs to the destination account, is not sent to it." } }, "required": [ "amount", "toPixKey" ] }, "InternalTransfer": { "type": "object", "properties": { "id": { "type": "string", "description": "Transfer identifier. The lookup accepts this `id` and the webhook `transferId`." }, "status": { "type": "string", "enum": [ "REQUESTED", "CONFIRMED", "FAILED" ], "description": "`REQUESTED`: no result yet, after a `502` where the bank did not respond or refused temporarily. `CONFIRMED`: the amount is in the other account. `FAILED`: it did not go out." }, "side": { "type": "string", "enum": [ "SENT", "RECEIVED" ], "description": "Side your account is on: `SENT` or `RECEIVED`." }, "amount": { "type": "integer", "description": "Amount that reached the destination. In cents." }, "serviceFee": { "type": "integer", "description": "Fee. `0` on the receiving side. In cents." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`. `0` on the receiving side. In cents." }, "counterparty": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the other account." }, "document": { "type": "string", "description": "Document of the other account: masked CPF or formatted CNPJ. Empty when unknown." }, "pixKey": { "type": "string", "description": "Key of the other account. In full in the `POST` response; in lookups and lists, CPF, email and phone keys are masked." } }, "required": [ "name", "document", "pixKey" ], "description": "The other account." }, "comment": { "type": [ "string", "null" ], "description": "Receipt text." }, "providerRejectedReason": { "type": [ "string", "null" ], "description": "Message ready to display, set when `FAILED`." }, "callbackUrl": { "type": [ "string", "null" ], "description": "The `callbackUrl` sent on creation. `null` when none was sent. `null` on the receiving side." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time in ISO 8601, UTC." }, "confirmedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it completed. `null` until it completes." }, "failedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it failed. `null` if it did not fail." } }, "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": "Sent and received transfers, newest first." }, "nextCursor": { "type": "string", "description": "Cursor for the next page. Absent on the last page." } }, "required": [ "data" ] }, "Deposit": { "type": "object", "properties": { "id": { "type": "string", "description": "Deposit identifier." }, "method": { "type": "string", "enum": [ "PIX" ], "description": "Always `PIX`." }, "amount": { "type": "integer", "description": "Amount the payer sent. In cents." }, "serviceFee": { "type": "integer", "description": "Receiving fee. In cents." }, "netAmount": { "type": "integer", "description": "`amount − serviceFee`: what was credited. In cents." }, "e2e": { "type": "string", "description": "End-to-end ID of the received Pix." }, "receiverPixKey": { "type": [ "string", "null" ], "description": "Key of your account that received it." }, "payer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Name of who paid." }, "document": { "type": [ "string", "null" ], "description": "Masked CPF or formatted CNPJ." }, "bankIspb": { "type": [ "string", "null" ], "description": "ISPB of the payer institution." }, "bankName": { "type": [ "string", "null" ], "description": "Payer institution." } }, "required": [ "name", "document", "bankIspb", "bankName" ], "description": "Who paid, as reported by the bank." }, "paidAt": { "type": "string", "format": "date-time", "description": "When the Pix arrived." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time in ISO 8601, UTC." }, "refundedAmount": { "type": "integer", "description": "How much has been returned, completed returns only. In cents." }, "refundInProgressAmount": { "type": "integer", "description": "Return still being processed. In cents." }, "refundableAmount": { "type": "integer", "description": "How much can still be returned. `0` while a return is still being processed or a dispute is open. In cents." }, "openInfractionProtocol": { "type": [ "string", "null" ], "description": "Protocol of the open MED dispute on the deposit. `null` when there is none." }, "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/RefundAttempt" }, "description": "Returns of the deposit, newest first." } }, "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`. In cents." }, "available": { "type": "integer", "description": "Balance available for withdrawals, Pix copy-and-paste payments and refunds. It is the sum of the statement lines. In cents." }, "blocked": { "type": "integer", "description": "Balance in the account that cannot be used: the sum of the three fields below. In cents." }, "blockedBySecurity": { "type": "integer", "description": "Held by an open MED dispute and by other blocks that are not withdrawals or refunds, such as the amount of a transfer with no result yet. In cents." }, "blockedByWithdraw": { "type": "integer", "description": "Held by a withdrawal still being processed. In cents." }, "blockedByRefund": { "type": "integer", "description": "Held by a refund still being processed. In cents." }, "syncedAt": { "type": "string", "format": "date-time", "description": "Time of the response." } }, "required": [ "total", "available", "blocked", "blockedBySecurity", "blockedByWithdraw", "blockedByRefund", "syncedAt" ] }, "StatementEntry": { "type": "object", "properties": { "id": { "type": "string", "description": "Line identifier. It is the value used as cursor." }, "entryId": { "type": "string", "description": "Entry. Lines with the same `entryId` came from the same event." }, "amount": { "type": "integer", "description": "Signed amount: positive came in, negative went out. In cents." }, "balanceAfter": { "type": "integer", "description": "Available balance after the line. In cents." }, "trigger": { "type": "string", "enum": [ "PAYMENT", "PAYMENT_REFUND", "DEPOSIT", "PAYOUT", "PAYOUT_REVERSAL", "INFRACTION_BLOCK", "INFRACTION_SETTLED", "INFRACTION_RELEASED", "INTERNAL_TRANSFER", "PAYOUT_REFUND_RECEIVED" ], "description": "What produced the line. `PAYMENT`: paid charge. `DEPOSIT`: Pix received without a charge. `PAYMENT_REFUND`: refund. `PAYOUT`: withdrawal or Pix copy-and-paste payment debit, at request time. `PAYOUT_REVERSAL`: amount back in the balance after a failure. `PAYOUT_REFUND_RECEIVED`: return of a sent Pix. `INFRACTION_BLOCK`: dispute opened. `INFRACTION_SETTLED`: dispute upheld. `INFRACTION_RELEASED`: dispute rejected or cancelled. `INTERNAL_TRANSFER`: transfer between accounts." }, "description": { "type": [ "string", "null" ], "description": "Short label, recorded with the entry. It does not change afterwards; the current state is in `status`." }, "originId": { "type": "string", "description": "Operation identifier (charge, withdrawal, deposit or transfer) as sent in the webhooks; it is not the charge, withdrawal or transfer `id`. On MED lines, the dispute identifier." }, "infractionProtocol": { "type": [ "string", "null" ], "description": "Dispute protocol, on MED lines." }, "gross": { "type": [ "integer", "null" ], "description": "Full operation amount. On receipts, what the payer paid; on withdrawals, what reached the destination. In cents." }, "fee": { "type": [ "integer", "null" ], "description": "Operation fee. In cents." }, "status": { "type": [ "string", "null" ], "enum": [ "PROCESSING", "SETTLED", "RETURNED" ], "description": "Current state of the line operation, for withdrawals, refunds and transfers: `PROCESSING`, `SETTLED` or `RETURNED`. `null` for the others." }, "statusDetail": { "type": [ "string", "null" ], "enum": [ "APPROVAL_REFUSED", "PROVIDER_REFUND" ], "description": "`APPROVAL_REFUSED`: the bank did not approve the withdrawal, and the amount stays out of the available balance. `PROVIDER_REFUND`: the bank returned the money to the payer without your request." }, "statusReason": { "type": [ "string", "null" ], "description": "Message ready to display, on `APPROVAL_REFUSED`." }, "statusAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the operation completed or returned." }, "payoutOperation": { "type": [ "string", "null" ], "enum": [ "WITHDRAW", "EXTERNAL_PAYMENT" ], "description": "On withdrawal lines: `WITHDRAW` (to a key) or `EXTERNAL_PAYMENT` (Pix copy-and-paste payment)." }, "counterparty": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "On incoming lines, the payer name; for a charge, the customer informed. `null` on outgoing Pix lines." }, "document": { "type": [ "string", "null" ], "description": "Document of that person. For a charge, in full; for a standalone Pix, masked." }, "pixKey": { "type": [ "string", "null" ], "description": "On outgoing lines, the masked destination key. On transfers between accounts, the key of the other account." } }, "required": [ "name", "document", "pixKey" ], "description": "Who the operation was with. `null` on dispute lines." }, "postedAt": { "type": "string", "format": "date-time", "description": "When the money moved." } }, "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": "Statement lines." }, "nextCursor": { "type": "string", "description": "Cursor for the next page. Absent on the last page." }, "balance": { "type": "integer", "description": "Available balance now, same as `available` in the balance. In cents." } }, "required": [ "data", "balance" ] }, "OperationLimits": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the operation is enabled for the account." }, "ticketMin": { "type": "integer", "description": "Minimum amount per operation. In cents." }, "ticketMax": { "type": "integer", "description": "Maximum amount per operation. In cents." }, "feeFixed": { "type": "integer", "description": "Fixed part of the fee. In cents." }, "feePercentage": { "type": "integer", "description": "Percentage part of the fee, in basis points (`150` = 1.5%)." } }, "required": [ "enabled", "ticketMin", "ticketMax", "feeFixed", "feePercentage" ] }, "DailyLimit": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "description": "Daily cap. `null` means no cap; `0` blocks every operation. In cents." }, "used": { "type": "integer", "description": "How much of the cap has been used today, Brasília time. Without a cap, `0`. In cents." } }, "required": [ "limit", "used" ] }, "AccountLimits": { "type": "object", "properties": { "payment": { "$ref": "#/components/schemas/OperationLimits", "description": "Charge." }, "withdraw": { "$ref": "#/components/schemas/OperationLimits", "description": "Withdrawal to a key. The minimum and maximum apply to every outgoing Pix." }, "externalPayment": { "$ref": "#/components/schemas/OperationLimits", "description": "Pix copy-and-paste payment: withdrawal limits, with its own fee." }, "refund": { "$ref": "#/components/schemas/OperationLimits", "description": "Refund and deposit return. The maximum per operation is the withdrawal one; the minimum is not checked." }, "internalTransfer": { "$ref": "#/components/schemas/OperationLimits", "description": "Transfer between PayZu accounts." }, "dailyWithdraw": { "$ref": "#/components/schemas/DailyLimit", "description": "Daily cap for outgoing Pix." }, "dailyInternalTransfer": { "$ref": "#/components/schemas/DailyLimit", "description": "Daily cap for transfers between accounts." }, "infraction": { "type": "object", "properties": { "feeFixed": { "type": "integer", "description": "Fixed part of the analysis fee for a rejected dispute. In cents." }, "feePercentage": { "type": "integer", "description": "Percentage part of the analysis fee, in basis points." }, "blocksBalance": { "type": "boolean", "description": "Whether the disputed amount leaves the available balance while the analysis runs." } }, "required": [ "feeFixed", "feePercentage", "blocksBalance" ], "description": "MED dispute." } }, "required": [ "payment", "withdraw", "externalPayment", "refund", "internalTransfer", "dailyWithdraw", "dailyInternalTransfer", "infraction" ] }, "RailMetrics": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "PIX", "BOLETO", "CREDITCARD" ], "description": "Payment method." }, "available": { "type": "boolean", "const": true, "description": "`true`: there are metrics for the method. Pix without charges in the period comes with zeroed figures." }, "created": { "type": "integer", "description": "Charges created in the period." }, "paid": { "type": "integer", "description": "Charges of the period that were paid, including those refunded later." }, "conversionRate": { "type": [ "integer", "null" ], "description": "`paid / created`, in basis points. `null` without charges." }, "paidAmount": { "type": "integer", "description": "Gross sum of what was paid. In cents." }, "averageTicket": { "type": [ "integer", "null" ], "description": "`paidAmount / paid`. `null` without payments. In cents." }, "refundedAmount": { "type": "integer", "description": "Returned to the payer, including partial refunds. In cents." }, "refundRate": { "type": [ "integer", "null" ], "description": "Refunded ratio, in basis points. `null` without a base." }, "disputedAmount": { "type": "integer", "description": "Amount under MED dispute. In cents." }, "disputeRate": { "type": [ "integer", "null" ], "description": "Disputed ratio, in basis points. `null` without a base." }, "pending": { "type": "integer", "description": "Charges of the period not yet paid." }, "pendingAmount": { "type": "integer", "description": "Sum of unpaid charges. In cents." }, "refunded": { "type": "integer", "description": "Charges with a refund, full or partial." } }, "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": "Payment method." }, "available": { "type": "boolean", "const": false, "description": "`false`: no metrics available for the method." } }, "required": [ "method", "available" ] }, "AccountMetrics": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "First instant counted." }, "to": { "type": "string", "format": "date-time", "description": "Last instant counted." } }, "required": [ "from", "to" ], "description": "Period actually used." }, "rails": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/RailMetrics" }, { "$ref": "#/components/schemas/UnavailableRailMetrics" } ] }, "description": "One item per payment method of the account. Charges count by creation date." }, "withdrawals": { "type": "object", "properties": { "count": { "type": "integer", "description": "Count." }, "amount": { "type": "integer", "description": "Total debited, including the fee. In cents." } }, "required": [ "count", "amount" ], "description": "Withdrawals of the period that did not fail." }, "deposits": { "type": "object", "properties": { "count": { "type": "integer", "description": "Count." }, "amount": { "type": "integer", "description": "Gross amount. In cents." }, "netAmount": { "type": "integer", "description": "Amount credited. In cents." } }, "required": [ "count", "amount", "netAmount" ], "description": "Pix received without a charge, by arrival date." }, "pixInflow": { "type": [ "object", "null" ], "properties": { "count": { "type": "integer", "description": "Count." }, "amount": { "type": "integer", "description": "Gross amount. In cents." } }, "required": [ "count", "amount" ], "description": "Everything that came in by Pix: paid charges and deposits. `null` when the account has no Pix." } }, "required": [ "period", "rails", "withdrawals", "deposits", "pixInflow" ] }, "Infraction": { "type": "object", "properties": { "id": { "type": "string", "description": "Dispute identifier at PayZu." }, "protocol": { "type": "string", "description": "Dispute protocol. It is the identifier used in the lookup and in the webhooks." }, "type": { "type": "string", "enum": [ "REFUND_REQUEST", "FRAUD", "REFUND_CANCELLED" ], "description": "Alleged reason." }, "status": { "type": "string", "enum": [ "OPEN", "ACKNOWLEDGED", "DEFENDED", "ANSWERED", "WAITING_PSP", "WAITING_ADJUSTMENTS", "CANCELLED", "CLOSED" ], "description": "Dispute stage. `OPEN`, `CLOSED` and `CANCELLED` move money; the others are steps between the banks. A cancelled dispute returns the full blocked amount, without an analysis fee." }, "reportedBy": { "type": "string", "enum": [ "DEBITED_PARTICIPANT", "CREDITED_PARTICIPANT" ], "description": "Side that opened the dispute." }, "reportDetails": { "type": "string", "description": "Report from who opened it." }, "analysisResult": { "type": [ "string", "null" ], "enum": [ "AGREED", "DISAGREED" ], "description": "Result, when `CLOSED`. `AGREED`: upheld, the amount returns to the payer. `DISAGREED`: rejected, the amount returns to the available balance, minus the analysis fee." }, "analysisDetails": { "type": [ "string", "null" ], "description": "Reason for the result." }, "endToEndId": { "type": "string", "description": "End-to-end ID of the disputed Pix." }, "blockedAmount": { "type": "integer", "description": "Amount set aside from the available balance while the analysis runs. In cents." }, "feeCharged": { "type": "integer", "description": "Analysis fee charged. `0` until the dispute is closed. In cents." }, "settledAmount": { "type": "integer", "description": "How much returned to the payer. `0` until the dispute is closed. In cents." }, "reportedAt": { "type": "string", "format": "date-time", "description": "When it was opened." }, "dueAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Deadline to respond. `null` when there is none." }, "closedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was closed." }, "origin": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PAYMENT", "DEPOSIT" ], "description": "`PAYMENT`: charge. `DEPOSIT`: Pix received without a charge." }, "id": { "type": "string", "description": "Charge or deposit identifier as sent in the webhooks." }, "amount": { "type": "integer", "description": "Amount received. In cents." }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was received." }, "payerName": { "type": [ "string", "null" ], "description": "For a charge, the customer informed; for a deposit, the payer reported by the bank." }, "payerDocument": { "type": [ "string", "null" ], "description": "Masked CPF or formatted CNPJ." } }, "required": [ "kind", "id", "amount", "paidAt", "payerName", "payerDocument" ], "description": "Disputed operation." } }, "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": "Account disputes, by opening date, newest first." }, "nextCursor": { "type": "string", "description": "Cursor for the next page. Absent on the last page." } }, "required": [ "data" ] }, "CreateWebhook": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTPS URL of the endpoint. Up to 2048 characters." }, "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": "Events the endpoint receives. At least one." }, "isActive": { "default": true, "type": "boolean", "description": "Whether the endpoint receives webhooks." } }, "required": [ "url", "events" ] }, "UpdateWebhook": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "New public HTTPS URL." }, "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": "New list of events. At least one." }, "isActive": { "type": "boolean", "description": "`false` stops sending webhooks to the endpoint immediately." } }, "minProperties": 1 }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "description": "Endpoint identifier." }, "url": { "type": "string", "description": "Endpoint URL." }, "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": "Subscribed events." }, "isActive": { "type": "boolean", "description": "Whether the endpoint receives webhooks." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time in ISO 8601, UTC." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time in 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": "Endpoint secret, prefixed with `whsec_`. It signs the webhooks and only appears in this response." } }, "required": [ "secret" ] } ] }, "CallbackSecret": { "type": "object", "properties": { "secret": { "type": "string", "description": "Account callback secret, prefixed with `cbsec_`. It signs the webhooks sent to the `callbackUrl` and only appears in this response." } }, "required": [ "secret" ] }, "CallbackSecretStatus": { "type": "object", "properties": { "hasCallbackSecret": { "type": "boolean", "description": "Whether the account already has a callback secret." } }, "required": [ "hasCallbackSecret" ] }, "PaymentCreatedEvent": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Charge identifier. Accepted by `GET /transactions/payment/{paymentId}`." }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "REFUNDED", "EXPIRED" ], "description": "`PENDING`." }, "amount": { "type": "integer", "description": "Amount charged, in cents." }, "method": { "type": "string", "enum": [ "PIX" ], "description": "`PIX`." }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date, ISO 8601." }, "qrCode": { "type": "string", "description": "Pix copy-and-paste code." }, "metadata": { "type": "object", "additionalProperties": true, "description": "The `metadata` sent on creation. Only when sent and not empty." }, "externalRef": { "type": "string", "description": "The `externalRef` sent on creation. Only when sent." } }, "required": [ "paymentId", "status", "amount", "method", "createdAt" ] }, "PaymentSettledEvent": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Charge identifier. Accepted by `GET /transactions/payment/{paymentId}`." }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "REFUNDED", "EXPIRED" ], "description": "`PAID` on `PAYMENT_PAID`; `REFUNDED` on `PAYMENT_REFUNDED`." }, "amount": { "type": "integer", "description": "Amount charged, in cents." }, "serviceFee": { "type": "integer", "description": "Receiving fee, in cents." }, "netAmount": { "type": "integer", "description": "`amount − serviceFee`: what was credited on receipt." }, "debitedAmount": { "type": "integer", "description": "Only on `PAYMENT_REFUNDED`: what left the account, the full amount." }, "serviceFeeReturned": { "type": "boolean", "description": "Only on `PAYMENT_REFUNDED`, always `false`." }, "endToEndId": { "type": "string", "description": "Pix end-to-end ID, when the bank reports it." }, "metadata": { "type": "object", "additionalProperties": true, "description": "The `metadata` sent on creation. Only when sent and not empty." }, "externalRef": { "type": "string", "description": "The `externalRef` sent on creation. Only when sent." } }, "required": [ "paymentId", "status", "amount", "serviceFee", "netAmount" ] }, "PaymentExpiredEvent": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Charge identifier. Accepted by `GET /transactions/payment/{paymentId}`." }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "REFUNDED", "EXPIRED" ], "description": "`EXPIRED`." }, "amount": { "type": "integer", "description": "Amount charged, in cents." }, "metadata": { "type": "object", "additionalProperties": true, "description": "The `metadata` sent on creation. Only when sent and not empty." }, "externalRef": { "type": "string", "description": "The `externalRef` sent on creation. Only when sent." } }, "required": [ "paymentId", "status", "amount" ] }, "WithdrawEvent": { "type": "object", "properties": { "withdrawId": { "type": "string", "description": "Withdrawal identifier. Accepted by `GET /transactions/withdraw/{withdrawId}`." }, "status": { "type": "string", "enum": [ "REQUESTED", "CREATED", "APPROVED", "CONFIRMED", "FAILED" ], "description": "`REQUESTED` on `WITHDRAW_CREATED`, `CONFIRMED` on `WITHDRAW_COMPLETED`, `FAILED` on `WITHDRAW_FAILED`." }, "operation": { "type": "string", "enum": [ "WITHDRAW", "EXTERNAL_PAYMENT" ], "description": "`WITHDRAW` (to a key) or `EXTERNAL_PAYMENT` (Pix copy-and-paste payment)." }, "amount": { "type": "integer", "description": "What reaches the destination, in cents." }, "serviceFee": { "type": "integer", "description": "Fee, added on top." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`." }, "pixKey": { "type": "string", "description": "Destination. For a withdrawal, the key sent; for a Pix copy-and-paste payment, masked (CPF, email and phone keys are masked; CNPJ and random keys are shown in full.)" }, "endToEndId": { "type": "string", "description": "Pix end-to-end ID, when the bank reports it." }, "reason": { "type": "string", "description": "Only on `WITHDRAW_FAILED`: message ready to display." } }, "required": [ "withdrawId", "status", "operation", "amount", "serviceFee", "totalDebited", "pixKey" ] }, "RefundEvent": { "type": "object", "properties": { "refundId": { "type": "string", "description": "Refund identifier." }, "paymentId": { "type": "string", "description": "When the refund is of a charge." }, "depositId": { "type": "string", "description": "When the refund is of a deposit. One of the two comes." }, "status": { "type": "string", "enum": [ "SETTLED", "RELEASED" ], "description": "`SETTLED` (returned to the payer) or `RELEASED` (refused, amount back in the balance)." }, "amount": { "type": "integer", "description": "What returns to the payer, in cents." }, "totalDebited": { "type": "integer", "description": "`amount` + refund fee." }, "endToEndId": { "type": "string", "description": "Only on `REFUND_COMPLETED`: end-to-end ID of the return Pix. May be absent." }, "reason": { "type": "string", "description": "Only on `REFUND_FAILED`, when present: message ready to display." } }, "required": [ "refundId", "status", "amount", "totalDebited" ] }, "DepositReceivedEvent": { "type": "object", "properties": { "depositId": { "type": "string", "description": "Deposit identifier. Accepted by `GET /transactions/deposit/{depositId}`." }, "amount": { "type": "integer", "description": "Amount received, in cents." }, "serviceFee": { "type": "integer", "description": "Fee, in cents." }, "netAmount": { "type": "integer", "description": "`amount − serviceFee`: what was credited." }, "endToEndId": { "type": "string", "description": "Pix end-to-end ID. Always present." }, "payerName": { "type": "string", "description": "Payer name, when the bank reports it." }, "payerDocument": { "type": "string", "description": "Payer CPF or CNPJ, as reported by the bank." } }, "required": [ "depositId", "amount", "serviceFee", "netAmount", "endToEndId" ] }, "WithdrawRefundReceivedEvent": { "type": "object", "properties": { "depositId": { "type": "string", "description": "Credit identifier." }, "withdrawId": { "type": "string", "description": "Withdrawal whose Pix came back." }, "amount": { "type": "integer", "description": "Returned amount, credited without a fee, in cents." }, "originalAmount": { "type": "integer", "description": "Amount that had gone out, in cents." }, "partial": { "type": "boolean", "description": "`true` when less came back than went out." }, "e2e": { "type": "string", "description": "End-to-end ID of the return." }, "originalE2e": { "type": "string", "description": "End-to-end ID of the Pix that went out." }, "returnedAt": { "type": "string", "format": "date-time", "description": "When the return was recorded." } }, "required": [ "depositId", "withdrawId", "amount", "originalAmount", "partial", "e2e", "originalE2e", "returnedAt" ] }, "InternalTransferSentEvent": { "type": "object", "properties": { "transferId": { "type": "string", "description": "Transfer identifier, the same on both sides." }, "status": { "type": "string", "const": "CONFIRMED", "description": "`CONFIRMED`." }, "amount": { "type": "integer", "description": "What went to the destination, in cents." }, "serviceFee": { "type": "integer", "description": "Fee, in cents." }, "totalDebited": { "type": "integer", "description": "`amount + serviceFee`." }, "toPixKey": { "type": "string", "description": "Destination key, masked when it is a CPF, phone or email." } }, "required": [ "transferId", "status", "amount", "serviceFee", "totalDebited", "toPixKey" ] }, "InternalTransferReceivedEvent": { "type": "object", "properties": { "transferId": { "type": "string", "description": "Transfer identifier, the same on both sides." }, "status": { "type": "string", "const": "CONFIRMED", "description": "`CONFIRMED`." }, "amount": { "type": "integer", "description": "What came in, in cents." }, "fromPixKey": { "type": "string", "description": "Key of the sending account, masked when it is a CPF, phone or email." } }, "required": [ "transferId", "status", "amount", "fromPixKey" ] }, "InfractionEvent": { "type": "object", "properties": { "protocol": { "type": "string", "description": "Dispute protocol." }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED", "CANCELLED" ], "description": "`OPEN` on opening; `CLOSED` or `CANCELLED` on closing." }, "paymentId": { "type": "string", "description": "When the dispute is about a charge." }, "depositId": { "type": "string", "description": "When the dispute is about a deposit. One of the two comes." }, "amount": { "type": "integer", "description": "Amount of the disputed charge or deposit, in cents." }, "reportDetails": { "type": "string", "description": "Report from who disputed." }, "analysisResult": { "type": "string", "enum": [ "AGREED", "DISAGREED" ], "description": "`AGREED` (upheld) or `DISAGREED` (rejected), when present." }, "dueAt": { "type": "string", "format": "date-time", "description": "Response deadline, when present." }, "blockedAmount": { "type": "integer", "description": "What was set aside from the balance, in cents. Only when greater than zero." }, "settledAmount": { "type": "integer", "description": "Only on `INFRACTION_CLOSED`: what returned to the payer, in cents." }, "feeCharged": { "type": "integer", "description": "Only on `INFRACTION_CLOSED`: analysis fee charged, in cents." } }, "required": [ "protocol", "status", "amount", "reportDetails" ] }, "InfractionDeadlineEvent": { "type": "object", "properties": { "protocol": { "type": "string", "description": "Dispute protocol." }, "paymentId": { "type": "string", "description": "When the dispute is about a charge." }, "depositId": { "type": "string", "description": "When the dispute is about a deposit." }, "amount": { "type": "integer", "description": "Disputed amount, in cents." }, "dueAt": { "type": "string", "format": "date-time", "description": "Response deadline." }, "hoursRemaining": { "type": "integer", "description": "`48`, `24` or `6`: hours left until the deadline." } }, "required": [ "protocol", "amount", "dueAt", "hoursRemaining" ] }, "AccountBlockingEvent": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "SUSPENDED", "ACTIVE" ], "description": "`SUSPENDED` on blocking, `ACTIVE` on unblocking." }, "blockings": { "type": "array", "items": { "type": "string" }, "description": "Blocks in force, as bank codes. Empty on unblocking." }, "blockedOperations": { "type": "array", "items": { "type": "string", "enum": [ "PIX_IN", "PIX_OUT", "INTERNAL_TRANSFER_OUT", "INTERNAL_TRANSFER_IN" ] }, "description": "What the API refuses while the list is in force: `PIX_IN`, `PIX_OUT`, `INTERNAL_TRANSFER_OUT`, `INTERNAL_TRANSFER_IN`." }, "changedAt": { "type": "string", "format": "date-time", "description": "When the change was recorded." } }, "required": [ "status", "blockings", "blockedOperations", "changedAt" ] } } } }