{ "openapi": "3.1.0", "info": { "title": "API da WysePay", "version": "1.0.0", "description": "Cobranças Pix, links de pagamento, clientes, saldo e saques. Autentique com a sua chave de API no header `x-api-key` (ou `Authorization: Bearer`). Chaves `wyp_test_` usam o modo teste; chaves `wyp_`, dinheiro real." }, "servers": [ { "url": "https://api.wysepay.com.br", "description": "A chave define o modo (teste ou produção)." } ], "security": [ { "apiKey": [] }, { "bearer": [] } ], "tags": [ { "name": "Cobranças Pix", "description": "Gere um Pix (QR Code e copia e cola) para um cliente." }, { "name": "Transações", "description": "Consulte e liste as cobranças." }, { "name": "Links de pagamento", "description": "Checkouts prontos para enviar ao cliente." }, { "name": "Clientes", "description": "A sua carteira de clientes, um por CPF ou CNPJ." }, { "name": "Saldo e saques", "description": "O saldo da conta e saques para chaves Pix." }, { "name": "Modo teste", "description": "Simule pagamentos com uma chave de teste." } ], "paths": { "/api/v1/charges/pix": { "post": { "operationId": "createPixCharge", "tags": [ "Cobranças Pix" ], "summary": "Gerar uma cobrança Pix", "description": "Cria a cobrança e devolve o código Pix (copia e cola e QR Code). O status começa em `WAITING_PAYMENT`; quando o cliente pagar, chega o webhook `transaction.paid`.\n\nPermissão da chave: `charges:write`.", "x-permission": "charges:write", "parameters": [ { "name": "idempotency-key", "in": "header", "required": false, "description": "Envie a mesma chave para repetir com segurança: a mesma cobrança volta, sem duplicar.", "schema": { "type": "string", "examples": [ "pedido-1042" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amountCents": { "type": "integer", "minimum": 500, "description": "Valor em centavos. Mínimo de 500 (R$ 5,00).", "examples": [ 8990 ] }, "description": { "type": "string", "minLength": 3, "maxLength": 180, "description": "O que está sendo cobrado. Aparece para o pagador.", "examples": [ "Pedido #1042" ] }, "customer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "examples": [ "Ana Souza" ] }, "email": { "type": "string", "format": "email", "examples": [ "ana@exemplo.com.br" ] }, "phone": { "type": "string", "minLength": 8, "description": "Com DDD, só dígitos.", "examples": [ "11912345678" ] }, "documentType": { "type": "string", "enum": [ "CPF", "CNPJ" ], "examples": [ "CPF" ] }, "document": { "type": "string", "minLength": 11, "description": "CPF ou CNPJ, só dígitos.", "examples": [ "12345678909" ] }, "address": { "type": "object", "properties": { "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "street": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "number": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "complement": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "description": "Opcional. Fica salvo no cadastro do cliente; não é enviado à adquirente." } }, "required": [ "name", "email", "phone", "documentType", "document" ], "description": "Quem paga. O CPF ou CNPJ é validado; inválido responde 400." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Quando o Pix (ou o link) deixa de aceitar pagamento, em ISO 8601 (ex.: 2026-12-31T23:59:00.000Z). Sem ele, vale o prazo padrão." }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Dados seus (ex.: o id do pedido). Voltam iguais na consulta e nos webhooks.", "examples": [ { "orderId": "1042" } ] } }, "required": [ "amountCents", "description", "customer" ] }, "example": { "amountCents": 8990, "description": "Pedido #1042", "customer": { "name": "Ana Souza", "email": "ana@exemplo.com.br", "phone": "11912345678", "documentType": "CPF", "document": "12345678909" }, "metadata": { "orderId": "1042" } } } } }, "responses": { "201": { "description": "Cobrança criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/transactions": { "get": { "operationId": "listTransactions", "tags": [ "Transações" ], "summary": "Listar transações", "description": "As cobranças da conta, da mais nova para a mais antiga, com filtros. Veja Paginação.\n\nPermissão da chave: `transactions:read`.", "x-permission": "transactions:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Quantos itens por página (1 a 100).", "schema": { "default": 20, "examples": [ 20 ], "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "startingAfter", "in": "query", "required": false, "description": "O `id` do último item da página anterior. A página seguinte começa depois dele.", "schema": { "examples": [ "txn_01k6g8m2v4x7z9b3c5d7f9h0j2" ], "type": "string", "maxLength": 64 } }, { "name": "status", "in": "query", "required": false, "description": "Só transações com este status.", "schema": { "examples": [ "PAID" ], "type": "string", "maxLength": 32 } }, { "name": "paymentLinkId", "in": "query", "required": false, "description": "Só as cobranças geradas por este link.", "schema": { "type": "string", "maxLength": 64 } }, { "name": "createdFrom", "in": "query", "required": false, "description": "Criadas a partir de (ISO 8601).", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, { "name": "createdTo", "in": "query", "required": false, "description": "Criadas antes de (ISO 8601).", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } } ], "responses": { "200": { "description": "Uma página de transações.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionList" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/transactions/{id}": { "get": { "operationId": "getTransaction", "tags": [ "Transações" ], "summary": "Consultar uma transação", "description": "A situação atual da cobrança. Um Pix vencido sem pagamento aparece como `EXPIRED`.\n\nPermissão da chave: `transactions:read`.", "x-permission": "transactions:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O `id` da transação (txn_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A transação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Transação não encontrada nesta conta e neste modo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/payment-links": { "post": { "operationId": "createPaymentLink", "tags": [ "Links de pagamento" ], "summary": "Criar um link de pagamento", "description": "Cria um checkout com o valor e a descrição. Envie a `url` ao cliente: ele preenche os dados, paga com Pix e vê o comprovante.\n\nPermissão da chave: `payment_links:write`.", "x-permission": "payment_links:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amountCents": { "type": "integer", "minimum": 500, "description": "Valor em centavos. Mínimo de 500 (R$ 5,00).", "examples": [ 8990 ] }, "description": { "type": "string", "minLength": 3, "maxLength": 180, "description": "O que está sendo cobrado. Aparece para o pagador.", "examples": [ "Pedido #1042" ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Quando o Pix (ou o link) deixa de aceitar pagamento, em ISO 8601 (ex.: 2026-12-31T23:59:00.000Z). Sem ele, vale o prazo padrão." }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Dados seus (ex.: o id do pedido). Voltam iguais na consulta e nos webhooks.", "examples": [ { "orderId": "1042" } ] }, "maxPayments": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000 }, { "type": "null" } ], "description": "Quantos pagamentos o link aceita. Omitido ou `null` = ilimitado; `1` = uso único." }, "returnUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Para onde o cliente volta depois de pagar (https). Recebe `wysepay_transaction_id` na URL. Confirme o pedido pelo webhook, não pelo retorno.", "examples": [ "https://loja.com.br/obrigado?pedido=1042" ] }, "askAddress": { "type": "boolean", "description": "O checkout pede o endereço do cliente (CEP preenche o resto)." } }, "required": [ "amountCents", "description" ] }, "example": { "amountCents": 8990, "description": "Pedido #1042", "metadata": { "orderId": "1042" }, "returnUrl": "https://loja.com.br/obrigado?pedido=1042" } } } }, "responses": { "201": { "description": "Link criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listPaymentLinks", "tags": [ "Links de pagamento" ], "summary": "Listar links de pagamento", "description": "Os links da conta, do mais novo para o mais antigo.\n\nPermissão da chave: `payment_links:read`.", "x-permission": "payment_links:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Quantos itens por página (1 a 100).", "schema": { "default": 20, "examples": [ 20 ], "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "startingAfter", "in": "query", "required": false, "description": "O `id` do último item da página anterior. A página seguinte começa depois dele.", "schema": { "examples": [ "txn_01k6g8m2v4x7z9b3c5d7f9h0j2" ], "type": "string", "maxLength": 64 } }, { "name": "active", "in": "query", "required": false, "description": "`true` só os ativos; `false` só os desativados ou esgotados.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Uma página de links.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkList" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/payment-links/{id}": { "get": { "operationId": "getPaymentLink", "tags": [ "Links de pagamento" ], "summary": "Consultar um link", "description": "Um link de pagamento e se ele ainda aceita pagamentos (`active`).\n\nPermissão da chave: `payment_links:read`.", "x-permission": "payment_links:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O `id` do link (plk_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "O link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Link não encontrado nesta conta e neste modo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/payment-links/{id}/deactivate": { "post": { "operationId": "deactivatePaymentLink", "tags": [ "Links de pagamento" ], "summary": "Desativar um link", "description": "O link para de aceitar pagamentos e o checkout mostra que ele não está disponível. Cobranças já geradas continuam valendo.\n\nPermissão da chave: `payment_links:write`.", "x-permission": "payment_links:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O `id` do link (plk_…).", "schema": { "type": "string" } } ], "responses": { "201": { "description": "O link, agora desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Link não encontrado nesta conta e neste modo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/customers": { "post": { "operationId": "saveCustomer", "tags": [ "Clientes" ], "summary": "Cadastrar um cliente", "description": "Cadastra o cliente, ou atualiza o que já tem esse CPF ou CNPJ (há um cliente por documento). Campos não enviados ficam como estavam.\n\nPermissão da chave: `customers:write`.", "x-permission": "customers:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120, "examples": [ "Ana Souza" ] }, "document": { "type": "string", "minLength": 11, "maxLength": 18, "description": "CPF ou CNPJ, com ou sem pontuação.", "examples": [ "12345678909" ] }, "email": { "examples": [ "ana@exemplo.com.br" ], "type": "string", "maxLength": 160, "format": "email" }, "phone": { "description": "Com DDD.", "examples": [ "11912345678" ], "type": "string", "maxLength": 20 }, "address": { "type": "object", "properties": { "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "street": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "number": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "complement": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "required": [ "name", "document" ] }, "example": { "name": "Ana Souza", "document": "12345678909", "email": "ana@exemplo.com.br", "phone": "11912345678" } } } }, "responses": { "201": { "description": "O cliente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listCustomers", "tags": [ "Clientes" ], "summary": "Listar clientes", "description": "Os clientes da conta, do mais novo para o mais antigo. Filtre por `document` para achar um CPF ou CNPJ.\n\nPermissão da chave: `customers:read`.", "x-permission": "customers:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Quantos itens por página (1 a 100).", "schema": { "default": 20, "examples": [ 20 ], "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "startingAfter", "in": "query", "required": false, "description": "O `id` do último item da página anterior. A página seguinte começa depois dele.", "schema": { "examples": [ "txn_01k6g8m2v4x7z9b3c5d7f9h0j2" ], "type": "string", "maxLength": 64 } }, { "name": "document", "in": "query", "required": false, "description": "Só o cliente deste CPF ou CNPJ (com ou sem pontuação).", "schema": { "type": "string", "maxLength": 18 } } ], "responses": { "200": { "description": "Uma página de clientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/customers/{id}": { "get": { "operationId": "getCustomer", "tags": [ "Clientes" ], "summary": "Consultar um cliente", "description": "Os dados e o endereço de um cliente.\n\nPermissão da chave: `customers:read`.", "x-permission": "customers:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O `id` do cliente (cus_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "O cliente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Cliente não encontrado nesta conta e neste modo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateCustomer", "tags": [ "Clientes" ], "summary": "Atualizar um cliente", "description": "Muda os campos enviados. O CPF ou CNPJ não muda.\n\nPermissão da chave: `customers:write`.", "x-permission": "customers:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O `id` do cliente (cus_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120, "examples": [ "Ana Souza" ] }, "email": { "examples": [ "ana@exemplo.com.br" ], "type": "string", "maxLength": 160, "format": "email" }, "phone": { "description": "Com DDD.", "examples": [ "11912345678" ], "type": "string", "maxLength": 20 }, "address": { "type": "object", "properties": { "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "street": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "number": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "complement": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } }, "example": { "name": "Ana Souza", "email": "ana@exemplo.com.br", "phone": "11912345678" } } } }, "responses": { "200": { "description": "O cliente atualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Cliente não encontrado nesta conta e neste modo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/balance": { "get": { "operationId": "getBalance", "tags": [ "Saldo e saques" ], "summary": "Consultar o saldo", "description": "Disponível, a liberar e bloqueado, e quanto dá para sacar agora.\n\nPermissão da chave: `balance:read`.", "x-permission": "balance:read", "responses": { "200": { "description": "O saldo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/withdrawals": { "post": { "operationId": "createWithdrawal", "tags": [ "Saldo e saques" ], "summary": "Sacar para uma chave Pix", "description": "Tira o valor do saldo e envia para a chave Pix. Precisa da permissão `withdrawals:write`, que vem desligada, e respeita o limite diário e os IPs da chave. Com chave de teste, o saque é simulado e pago na hora.\n\nPermissão da chave: `withdrawals:write`.", "x-permission": "withdrawals:write", "parameters": [ { "name": "idempotency-key", "in": "header", "required": false, "description": "Envie a mesma chave para repetir com segurança: o mesmo saque volta, sem sacar de novo.", "schema": { "type": "string", "examples": [ "pedido-1042" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amountCents": { "type": "integer", "minimum": 600, "description": "Quanto sai do saldo, em centavos, já incluindo a taxa de saque. Mínimo 600 (R$ 6,00).", "examples": [ 50000 ] }, "pixKey": { "type": "string", "minLength": 3, "maxLength": 140, "description": "A chave Pix de destino.", "examples": [ "12345678000190" ] }, "pixKeyType": { "type": "string", "enum": [ "CPF", "CNPJ", "PHONE", "EMAIL", "EVP" ], "description": "`CPF`, `CNPJ`, `PHONE` (celular com DDD), `EMAIL` ou `EVP` (chave aleatória).", "examples": [ "CNPJ" ] } }, "required": [ "amountCents", "pixKey", "pixKeyType" ] }, "example": { "amountCents": 50000, "pixKey": "12345678000190", "pixKeyType": "CNPJ" } } } }, "responses": { "201": { "description": "O saque.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdrawal" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Sem permissão, IP não liberado, conta não verificada ou limite diário da chave atingido (`WITHDRAW_DAILY_LIMIT`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listWithdrawals", "tags": [ "Saldo e saques" ], "summary": "Listar saques", "description": "Os saques da conta (pelo painel e pela API), do mais novo para o mais antigo.\n\nPermissão da chave: `withdrawals:read`.", "x-permission": "withdrawals:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Quantos itens por página (1 a 100).", "schema": { "default": 20, "examples": [ 20 ], "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "startingAfter", "in": "query", "required": false, "description": "O `id` do último item da página anterior. A página seguinte começa depois dele.", "schema": { "examples": [ "txn_01k6g8m2v4x7z9b3c5d7f9h0j2" ], "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "Uma página de saques.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalList" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/withdrawals/{id}": { "get": { "operationId": "getWithdrawal", "tags": [ "Saldo e saques" ], "summary": "Consultar um saque", "description": "A situação de um saque.\n\nPermissão da chave: `withdrawals:read`.", "x-permission": "withdrawals:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O `id` do saque (wd_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "O saque.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdrawal" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Saque não encontrado nesta conta e neste modo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sandbox/transactions/{id}/pay": { "post": { "operationId": "simulatePayment", "tags": [ "Modo teste" ], "summary": "Simular o pagamento", "description": "Só com chave de teste: marca a cobrança de teste como paga e envia o webhook `transaction.paid`, como num pagamento real.\n\nPermissão da chave: `charges:write`.", "x-permission": "charges:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O `id` de uma transação de teste.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "A transação, agora paga.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "description": "Dados inválidos. A mensagem diz o campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Transação não encontrada nesta conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Muitas requisições. Espere o tempo do header `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "transaction.created": { "post": { "summary": "Cobrança criada", "description": "Um Pix foi gerado (pela API, pelo painel ou por um link).", "parameters": [ { "name": "wysepay-event", "in": "header", "required": true, "description": "O tipo do evento.", "schema": { "type": "string" } }, { "name": "wysepay-signature", "in": "header", "required": true, "description": "HMAC-SHA256 (hex) de `{wysepay-timestamp}.{corpo}` com o segredo do endpoint.", "schema": { "type": "string" } }, { "name": "wysepay-timestamp", "in": "header", "required": true, "description": "Milissegundos desde 1970.", "schema": { "type": "string" } }, { "name": "wysepay-delivery-id", "in": "header", "required": true, "description": "Id da entrega; igual nas novas tentativas.", "schema": { "type": "string" } }, { "name": "wysepay-attempt", "in": "header", "required": true, "description": "Número da tentativa (1 a 6).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "responses": { "200": { "description": "Responda 2xx em até 8 s para confirmar o recebimento." } } } }, "transaction.paid": { "post": { "summary": "Cobrança paga", "description": "O pagamento foi confirmado. Use este evento para liberar o pedido.", "parameters": [ { "name": "wysepay-event", "in": "header", "required": true, "description": "O tipo do evento.", "schema": { "type": "string" } }, { "name": "wysepay-signature", "in": "header", "required": true, "description": "HMAC-SHA256 (hex) de `{wysepay-timestamp}.{corpo}` com o segredo do endpoint.", "schema": { "type": "string" } }, { "name": "wysepay-timestamp", "in": "header", "required": true, "description": "Milissegundos desde 1970.", "schema": { "type": "string" } }, { "name": "wysepay-delivery-id", "in": "header", "required": true, "description": "Id da entrega; igual nas novas tentativas.", "schema": { "type": "string" } }, { "name": "wysepay-attempt", "in": "header", "required": true, "description": "Número da tentativa (1 a 6).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "responses": { "200": { "description": "Responda 2xx em até 8 s para confirmar o recebimento." } } } }, "transaction.expired": { "post": { "summary": "Cobrança vencida", "description": "O Pix passou do `expiresAt` sem pagamento. Cancele o pedido ou gere uma cobrança nova.", "parameters": [ { "name": "wysepay-event", "in": "header", "required": true, "description": "O tipo do evento.", "schema": { "type": "string" } }, { "name": "wysepay-signature", "in": "header", "required": true, "description": "HMAC-SHA256 (hex) de `{wysepay-timestamp}.{corpo}` com o segredo do endpoint.", "schema": { "type": "string" } }, { "name": "wysepay-timestamp", "in": "header", "required": true, "description": "Milissegundos desde 1970.", "schema": { "type": "string" } }, { "name": "wysepay-delivery-id", "in": "header", "required": true, "description": "Id da entrega; igual nas novas tentativas.", "schema": { "type": "string" } }, { "name": "wysepay-attempt", "in": "header", "required": true, "description": "Número da tentativa (1 a 6).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "responses": { "200": { "description": "Responda 2xx em até 8 s para confirmar o recebimento." } } } }, "dispute.created": { "post": { "summary": "MED aberto", "description": "O pagador contestou um pagamento pelo banco dele.", "parameters": [ { "name": "wysepay-event", "in": "header", "required": true, "description": "O tipo do evento.", "schema": { "type": "string" } }, { "name": "wysepay-signature", "in": "header", "required": true, "description": "HMAC-SHA256 (hex) de `{wysepay-timestamp}.{corpo}` com o segredo do endpoint.", "schema": { "type": "string" } }, { "name": "wysepay-timestamp", "in": "header", "required": true, "description": "Milissegundos desde 1970.", "schema": { "type": "string" } }, { "name": "wysepay-delivery-id", "in": "header", "required": true, "description": "Id da entrega; igual nas novas tentativas.", "schema": { "type": "string" } }, { "name": "wysepay-attempt", "in": "header", "required": true, "description": "Número da tentativa (1 a 6).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeEvent" } } } }, "responses": { "200": { "description": "Responda 2xx em até 8 s para confirmar o recebimento." } } } }, "dispute.responded": { "post": { "summary": "MED respondido", "description": "A sua defesa do MED foi enviada.", "parameters": [ { "name": "wysepay-event", "in": "header", "required": true, "description": "O tipo do evento.", "schema": { "type": "string" } }, { "name": "wysepay-signature", "in": "header", "required": true, "description": "HMAC-SHA256 (hex) de `{wysepay-timestamp}.{corpo}` com o segredo do endpoint.", "schema": { "type": "string" } }, { "name": "wysepay-timestamp", "in": "header", "required": true, "description": "Milissegundos desde 1970.", "schema": { "type": "string" } }, { "name": "wysepay-delivery-id", "in": "header", "required": true, "description": "Id da entrega; igual nas novas tentativas.", "schema": { "type": "string" } }, { "name": "wysepay-attempt", "in": "header", "required": true, "description": "Número da tentativa (1 a 6).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeEvent" } } } }, "responses": { "200": { "description": "Responda 2xx em até 8 s para confirmar o recebimento." } } } }, "dispute.won": { "post": { "summary": "MED ganho", "description": "A contestação foi negada: o valor volta a ficar disponível para você.", "parameters": [ { "name": "wysepay-event", "in": "header", "required": true, "description": "O tipo do evento.", "schema": { "type": "string" } }, { "name": "wysepay-signature", "in": "header", "required": true, "description": "HMAC-SHA256 (hex) de `{wysepay-timestamp}.{corpo}` com o segredo do endpoint.", "schema": { "type": "string" } }, { "name": "wysepay-timestamp", "in": "header", "required": true, "description": "Milissegundos desde 1970.", "schema": { "type": "string" } }, { "name": "wysepay-delivery-id", "in": "header", "required": true, "description": "Id da entrega; igual nas novas tentativas.", "schema": { "type": "string" } }, { "name": "wysepay-attempt", "in": "header", "required": true, "description": "Número da tentativa (1 a 6).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeEvent" } } } }, "responses": { "200": { "description": "Responda 2xx em até 8 s para confirmar o recebimento." } } } }, "dispute.lost": { "post": { "summary": "MED perdido", "description": "A devolução foi confirmada: o valor foi devolvido ao pagador.", "parameters": [ { "name": "wysepay-event", "in": "header", "required": true, "description": "O tipo do evento.", "schema": { "type": "string" } }, { "name": "wysepay-signature", "in": "header", "required": true, "description": "HMAC-SHA256 (hex) de `{wysepay-timestamp}.{corpo}` com o segredo do endpoint.", "schema": { "type": "string" } }, { "name": "wysepay-timestamp", "in": "header", "required": true, "description": "Milissegundos desde 1970.", "schema": { "type": "string" } }, { "name": "wysepay-delivery-id", "in": "header", "required": true, "description": "Id da entrega; igual nas novas tentativas.", "schema": { "type": "string" } }, { "name": "wysepay-attempt", "in": "header", "required": true, "description": "Número da tentativa (1 a 6).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeEvent" } } } }, "responses": { "200": { "description": "Responda 2xx em até 8 s para confirmar o recebimento." } } } }, "withdrawal.created": { "post": { "summary": "Saque criado", "description": "Um saque foi pedido, pelo painel ou pela API.", "parameters": [ { "name": "wysepay-event", "in": "header", "required": true, "description": "O tipo do evento.", "schema": { "type": "string" } }, { "name": "wysepay-signature", "in": "header", "required": true, "description": "HMAC-SHA256 (hex) de `{wysepay-timestamp}.{corpo}` com o segredo do endpoint.", "schema": { "type": "string" } }, { "name": "wysepay-timestamp", "in": "header", "required": true, "description": "Milissegundos desde 1970.", "schema": { "type": "string" } }, { "name": "wysepay-delivery-id", "in": "header", "required": true, "description": "Id da entrega; igual nas novas tentativas.", "schema": { "type": "string" } }, { "name": "wysepay-attempt", "in": "header", "required": true, "description": "Número da tentativa (1 a 6).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalEvent" } } } }, "responses": { "200": { "description": "Responda 2xx em até 8 s para confirmar o recebimento." } } } }, "withdrawal.paid": { "post": { "summary": "Saque pago", "description": "O dinheiro chegou na chave Pix de destino.", "parameters": [ { "name": "wysepay-event", "in": "header", "required": true, "description": "O tipo do evento.", "schema": { "type": "string" } }, { "name": "wysepay-signature", "in": "header", "required": true, "description": "HMAC-SHA256 (hex) de `{wysepay-timestamp}.{corpo}` com o segredo do endpoint.", "schema": { "type": "string" } }, { "name": "wysepay-timestamp", "in": "header", "required": true, "description": "Milissegundos desde 1970.", "schema": { "type": "string" } }, { "name": "wysepay-delivery-id", "in": "header", "required": true, "description": "Id da entrega; igual nas novas tentativas.", "schema": { "type": "string" } }, { "name": "wysepay-attempt", "in": "header", "required": true, "description": "Número da tentativa (1 a 6).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalEvent" } } } }, "responses": { "200": { "description": "Responda 2xx em até 8 s para confirmar o recebimento." } } } }, "withdrawal.partially_paid": { "post": { "summary": "Saque pago em parte", "description": "Parte das transferências do saque não foi concluída; o valor dela voltou ao saldo.", "parameters": [ { "name": "wysepay-event", "in": "header", "required": true, "description": "O tipo do evento.", "schema": { "type": "string" } }, { "name": "wysepay-signature", "in": "header", "required": true, "description": "HMAC-SHA256 (hex) de `{wysepay-timestamp}.{corpo}` com o segredo do endpoint.", "schema": { "type": "string" } }, { "name": "wysepay-timestamp", "in": "header", "required": true, "description": "Milissegundos desde 1970.", "schema": { "type": "string" } }, { "name": "wysepay-delivery-id", "in": "header", "required": true, "description": "Id da entrega; igual nas novas tentativas.", "schema": { "type": "string" } }, { "name": "wysepay-attempt", "in": "header", "required": true, "description": "Número da tentativa (1 a 6).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalEvent" } } } }, "responses": { "200": { "description": "Responda 2xx em até 8 s para confirmar o recebimento." } } } }, "withdrawal.failed": { "post": { "summary": "Saque não concluído", "description": "O saque não foi feito; o valor voltou ao saldo.", "parameters": [ { "name": "wysepay-event", "in": "header", "required": true, "description": "O tipo do evento.", "schema": { "type": "string" } }, { "name": "wysepay-signature", "in": "header", "required": true, "description": "HMAC-SHA256 (hex) de `{wysepay-timestamp}.{corpo}` com o segredo do endpoint.", "schema": { "type": "string" } }, { "name": "wysepay-timestamp", "in": "header", "required": true, "description": "Milissegundos desde 1970.", "schema": { "type": "string" } }, { "name": "wysepay-delivery-id", "in": "header", "required": true, "description": "Id da entrega; igual nas novas tentativas.", "schema": { "type": "string" } }, { "name": "wysepay-attempt", "in": "header", "required": true, "description": "Número da tentativa (1 a 6).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalEvent" } } } }, "responses": { "200": { "description": "Responda 2xx em até 8 s para confirmar o recebimento." } } } } }, "components": { "schemas": { "TransactionCustomer": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "cus_01k6g8m2v4x7z9b3c5d7f9h0j2" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Ana Souza" ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "ana@exemplo.com.br" ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "11912345678" ] }, "documentType": { "type": "string", "enum": [ "CPF", "CNPJ" ] }, "document": { "type": "string", "description": "Só dígitos.", "examples": [ "12345678909" ] } }, "required": [ "id", "name", "email", "phone", "documentType", "document" ], "additionalProperties": false, "description": "Quem paga." }, "Transaction": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "txn_01k6g8m2v4x7z9b3c5d7f9h0j2" ] }, "status": { "type": "string", "enum": [ "CREATED", "WAITING_PAYMENT", "PENDING", "PROCESSING", "AUTHORIZED", "PAID", "EXPIRED", "CANCELLED", "FAILED", "REFUSED", "REFUNDED", "DISPUTE", "CHARGEDBACK", "BLOCKED" ], "examples": [ "WAITING_PAYMENT" ], "description": "Situação da cobrança. As mais comuns: `WAITING_PAYMENT` (Pix gerado, aguardando), `PAID` (pago) e `EXPIRED` (venceu sem pagamento)." }, "amountCents": { "type": "integer", "description": "Valor cobrado, em centavos.", "examples": [ 8990 ] }, "feeCents": { "type": "integer", "description": "Taxa da WysePay, em centavos.", "examples": [ 90 ] }, "netAmountCents": { "type": "integer", "description": "O que entra no seu saldo: valor menos a taxa.", "examples": [ 8900 ] }, "description": { "type": "string", "examples": [ "Pedido #1042" ] }, "pix": { "type": "object", "properties": { "copyPaste": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código Pix copia e cola.", "examples": [ "00020101021226850014br.gov.bcb.pix…6304A1B2" ] }, "qrCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Conteúdo do QR Code (o mesmo código, para gerar a imagem).", "examples": [ "00020101021226850014br.gov.bcb.pix…6304A1B2" ] } }, "required": [ "copyPaste", "qrCode" ], "additionalProperties": false, "description": "Dados para o pagador pagar." }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/TransactionCustomer" }, { "type": "null" } ] }, "paymentLinkId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "O link de pagamento que gerou esta cobrança, quando houver." }, "dispute": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "examples": [ "OPEN" ] }, "amountCents": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] } }, "required": [ "id", "status", "amountCents", "createdAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "MED (contestação) aberto sobre este pagamento, se houver." }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "O que você enviou em `metadata` ao criar a cobrança.", "examples": [ { "orderId": "1042" } ] }, "livemode": { "type": "boolean", "description": "`false` quando criada com uma chave de teste." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] } }, "required": [ "id", "status", "amountCents", "feeCents", "netAmountCents", "description", "pix", "customer", "paymentLinkId", "dispute", "metadata", "livemode", "expiresAt", "paidAt", "createdAt", "updatedAt" ], "additionalProperties": false, "description": "Uma cobrança Pix." }, "PaymentLink": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "plk_01k6g8m2v4x7z9b3c5d7f9h0j2" ] }, "url": { "type": "string", "format": "uri", "description": "Endereço do checkout para enviar ao cliente.", "examples": [ "https://app.wysepay.com.br/checkout/pay_2sngtnj5fkcnnm1m6v39xfe5b3" ] }, "amountCents": { "type": "integer", "examples": [ 8990 ] }, "description": { "type": "string", "examples": [ "Camiseta básica · Tamanho M" ] }, "active": { "type": "boolean", "description": "`false` depois de desativado ou esgotado." }, "maxPayments": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Quantos pagamentos o link aceita. `null` = ilimitado; `1` = uso único." }, "askAddress": { "type": "boolean", "description": "O checkout pede o endereço do cliente." }, "returnUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Para onde o cliente volta depois de pagar, com `wysepay_transaction_id` na URL." }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "livemode": { "type": "boolean" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] } }, "required": [ "id", "url", "amountCents", "description", "active", "maxPayments", "askAddress", "returnUrl", "metadata", "livemode", "expiresAt", "createdAt" ], "additionalProperties": false, "description": "Um link de pagamento." }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "cus_01k6g8m2v4x7z9b3c5d7f9h0j2" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Ana Souza" ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "ana@exemplo.com.br" ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "11912345678" ] }, "documentType": { "type": "string", "enum": [ "CPF", "CNPJ" ] }, "document": { "type": "string", "description": "Só dígitos.", "examples": [ "12345678909" ] }, "address": { "anyOf": [ { "type": "object", "properties": { "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "01310100" ] }, "street": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Avenida Paulista" ] }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "1000" ] }, "complement": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Bela Vista" ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "São Paulo" ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "SP" ] } }, "required": [ "zipCode", "street", "number", "complement", "district", "city", "state" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` quando nenhum campo do endereço foi informado." }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] } }, "required": [ "id", "name", "email", "phone", "documentType", "document", "address", "livemode", "createdAt", "updatedAt" ], "additionalProperties": false, "description": "Um cliente, um por CPF ou CNPJ em cada modo." }, "Balance": { "type": "object", "properties": { "availableCents": { "type": "integer", "description": "O que já pode ser sacado.", "examples": [ 125000 ] }, "pendingCents": { "type": "integer", "description": "Vendas pagas ainda no prazo de liberação.", "examples": [ 8900 ] }, "blockedCents": { "type": "integer", "description": "Retido, por exemplo, por um MED em andamento.", "examples": [ 0 ] }, "withdrawableNowCents": { "type": "integer", "description": "Quanto dá para sacar agora, num saque só (já considera a taxa e os mínimos).", "examples": [ 124900 ] }, "withdrawFeeCents": { "type": "integer", "description": "Taxa de cada saque.", "examples": [ 100 ] }, "livemode": { "type": "boolean" } }, "required": [ "availableCents", "pendingCents", "blockedCents", "withdrawableNowCents", "withdrawFeeCents", "livemode" ], "additionalProperties": false, "description": "O saldo da conta, no modo da chave." }, "Withdrawal": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "wd_01k6g8m2v4x7z9b3c5d7f9h0j2" ] }, "status": { "type": "string", "enum": [ "CREATED", "PENDING", "APPROVED", "PAID", "PARTIALLY_PAID", "FAILED", "CANCELLED" ], "description": "`PENDING` enquanto é enviado; `PAID`, `PARTIALLY_PAID` ou `FAILED` no fim.", "examples": [ "PAID" ] }, "amountCents": { "type": "integer", "description": "O que chega no destino.", "examples": [ 49900 ] }, "feeCents": { "type": "integer", "description": "A taxa de saque.", "examples": [ 100 ] }, "pixKeyType": { "type": "string", "enum": [ "CPF", "CNPJ", "PHONE", "EMAIL", "EVP" ] }, "pixKey": { "type": "string", "description": "A chave de destino, parcialmente escondida.", "examples": [ "12.***.***/0001-90" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] } }, "required": [ "id", "status", "amountCents", "feeCents", "pixKeyType", "pixKey", "livemode", "createdAt", "updatedAt" ], "additionalProperties": false, "description": "Um saque do saldo para uma chave Pix." }, "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "code": { "type": "string", "description": "`VALIDATION_ERROR` quando algum campo é inválido; `REQUEST_ERROR` nos demais erros do pedido; `INTERNAL_ERROR` em falhas nossas.", "examples": [ "VALIDATION_ERROR" ] }, "message": { "type": "string", "examples": [ "Revise os campos informados." ] }, "errors": { "description": "Em `VALIDATION_ERROR`: cada campo com problema e o motivo.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "examples": [ "customer.document" ] }, "message": { "type": "string", "examples": [ "CPF ou CNPJ inválido." ] } }, "required": [ "path", "message" ], "additionalProperties": false } }, "path": { "type": "string", "examples": [ "/api/v1/charges/pix" ] }, "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] } }, "required": [ "ok", "code", "message", "path", "timestamp" ], "additionalProperties": false, "description": "Toda resposta de erro tem este formato." }, "DisputeEvent": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "med_01k6g8m2v4x7z9b3c5d7f9h0j2" ] }, "transactionId": { "type": "string", "examples": [ "txn_01k6g8m2v4x7z9b3c5d7f9h0j2" ] }, "status": { "type": "string", "description": "Situação do MED.", "examples": [ "OPEN" ] }, "amountCents": { "type": "integer", "description": "Valor contestado, em centavos.", "examples": [ 8990 ] } }, "required": [ "id", "transactionId", "status", "amountCents" ], "additionalProperties": false, "description": "MED (Mecanismo Especial de Devolução) sobre um pagamento." }, "WithdrawalEvent": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "wd_01k6g8m2v4x7z9b3c5d7f9h0j2" ] }, "livemode": { "type": "boolean" }, "status": { "type": "string", "examples": [ "PAID" ] }, "amountCents": { "type": "integer", "description": "Valor do saque, em centavos.", "examples": [ 50000 ] }, "feeCents": { "type": "integer", "description": "Tarifa do saque, em centavos.", "examples": [ 0 ] }, "pixKeyType": { "type": "string", "examples": [ "CNPJ" ] }, "transfers": { "description": "Em quantas transferências o saque foi feito (eventos de conclusão).", "type": "integer" }, "returnedCents": { "description": "Quanto voltou ao saldo por transferências que não foram concluídas.", "type": "integer" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "examples": [ "2026-10-04T15:30:00.000Z" ] } }, "required": [ "id", "livemode", "status", "amountCents", "feeCents", "pixKeyType" ], "additionalProperties": false, "description": "Um saque feito no painel." }, "TransactionList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "hasMore": { "type": "boolean", "description": "`true` quando há mais itens: peça de novo com `startingAfter` = o `id` do último." } }, "required": [ "data", "hasMore" ] }, "PaymentLinkList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } }, "hasMore": { "type": "boolean", "description": "`true` quando há mais itens: peça de novo com `startingAfter` = o `id` do último." } }, "required": [ "data", "hasMore" ] }, "CustomerList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "hasMore": { "type": "boolean", "description": "`true` quando há mais itens: peça de novo com `startingAfter` = o `id` do último." } }, "required": [ "data", "hasMore" ] }, "WithdrawalList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Withdrawal" } }, "hasMore": { "type": "boolean", "description": "`true` quando há mais itens: peça de novo com `startingAfter` = o `id` do último." } }, "required": [ "data", "hasMore" ] } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Sua chave de API, criada no painel em Desenvolvedores → Chaves de API." }, "bearer": { "type": "http", "scheme": "bearer", "description": "A mesma chave, em `Authorization: Bearer wyp_…`." } } } }