{"info":{"_postman_id":"56c31d29-6c87-4ebb-8429-19693fd6678d","name":"Documentação ValidaPay2","schema":"https://schema.getpostman.com/json/collection/v2.1.0/collection.json","_exporter_id":"17189861"},"item":[{"name":"Pix","item":[{"name":"Status de cobrança","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/charges/:chargeId//Identificador retornado no ato da geraçao da cobrança","protocol":"https","host":["api","validapay","com","br"],"path":["v1","charges",":chargeId","","Identificador retornado no ato da geraçao da cobrança"],"variable":[{"key":"chargeId","value":""}]},"description":"@scopes pix.cob/read\n\n@top"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{VALIDAPAY_PRD_URL}}/v1/charges/cha_1771453171013_fp6iocaxb//Retornado no ato da geração da cobrança","host":["{{VALIDAPAY_PRD_URL}}"],"path":["v1","charges","cha_1771453171013_fp6iocaxb","","Retornado no ato da geração da cobrança"]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Fri, 20 Feb 2026 12:15:57 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"425"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"b50b94d6-630e-4954-9180-01cc9ac260ae"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"ZFGDTFqwoAMEitg="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-6998507b-56448c8c14b81f674ce2d166;Parent=2c3092a237905812;Sampled=0;Lineage=1:d488af6c:0"}],"cookie":[],"body":"{\n    \"chargeId\": \"cha_1771453171013_fp6iocaxb\",\n    \"status\": \"PAID\",\n    \"amount\": 0.2,\n    \"paymentType\": \"PIX\",\n    \"emv\": \"00020101021226910014br.gov.bcb.pix…\",\n    \"paidAt\": \"2026-02-18T22:22:50.031Z\",\n    \"createdAt\": \"2026-02-18T22:19:31.013Z\"\n}"}]},{"name":"Cobrança imediata","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[{"key":"","value":"","type":"text","disabled":true}],"body":{"mode":"raw","raw":"{\n  \"amount\": 10.00,\n  \"paymentMethod\": \"pix\",\n  \"expiration\": \"2026-12-31\",\n  \"externalTxid\": \"loja-01-caixa-03\",\n  \"metadata\": { \"orderId\": \"pedido-1001\" },\n  \"customer\": {\n    \"documentNumber\": \"12345678901\",\n    \"name\": \"Joao da Silva\",\n    \"cep\": \"01310100\",\n    \"phone\": \"+5511999998888\",\n    \"email\": \"joao@email.com\"\n  },\n  \"split\": [\n    {\n      \"type\": \"fixed\",\n      \"accountNumber\": \"896532569\",\n      \"amount\": 0.10\n    }\n  ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/charges/pix","protocol":"https","host":["api","validapay","com","br"],"path":["v1","charges","pix"]},"description":"@scopes pix.cob/write  \n@top\n\nCom esta funcionalidade você pode criar um QR Code de cobrança imediata.\n\n**Case de uso:**\n\n_Como SaaS, quero gerar cobranças preenchendo apenas o valor do produto e nada mais_\n\n**Regras condicionais (COBV):** `name` e `cep` do `customer` só são aceitos junto com `expiration`. Havendo `expiration` e `customer`, o trio `documentNumber`, `name` e `cep` passa a ser obrigatório em bloco.\n\n**Resposta:** os campos vêm na raiz — `emv` e `qrCode`, não aninhados sob `pix`. O `qrCode` já é uma data URL PNG pronta para exibir; não é preciso gerar a imagem no seu lado.\n\n**Correlação com o pedido:** envie `metadata` na criação e ele volta na resposta e no payload do webhook `payment.success`. É a forma recomendada de amarrar o pagamento ao seu pedido.\n\n> ⚠️ **Esta rota não tem idempotência.** `externalId` é aceito e descartado; duas chamadas iguais criam **duas cobranças**. Controle duplicidade no seu lado (índice `pedido → cobrança`) ou use `POST /v1/charges`, que responde `409 DUPLICATE_CHARGE`. O campo `externalTxid` documentado aqui identifica loja, caixa ou vendedor — não serve como chave de idempotência.\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `amount` | sim | Valor em reais, nunca em centavos (mín.: 0.01) |\n| `paymentMethod` | não | Fixo \"pix\"; o padrao ja e pix (valores: pix) |\n| `expiration` | não | Vencimento (COBV). Nao aceita data passada |\n| `externalTxid` | não | Identifica loja, caixa ou vendedor |\n| `customer` | não | Dados do pagador. Com expiration, vira COBV |\n| `customer.documentNumber` | não | CPF ou CNPJ do pagador |\n| `customer.name` | não | Exige expiration (COBV) |\n| `customer.cep` | não | Exige expiration (COBV) |\n| `customer.phone` | não | Telefone no formato E.164 |\n| `customer.email` | não | E-mail do pagador |\n| `split` | não | Divisao do valor entre recebedores |\n| `split.type` | sim | Tipo da divisao (valores: percentage, fixed) |\n| `split.accountNumber` | não | Conta do recebedor; ou informe publicId |\n| `split.amount` | sim | Valor em reais quando fixed; percentual de 0 a 100 quando percentage (mín.: 0.01) |"},"response":[{"name":"200","originalRequest":{"method":"POST","header":[{"key":"x-account-number","value":"428965347","type":"text"},{"key":"Origin","value":"{{ORIGIN}}","type":"text","disabled":true}],"url":{"raw":"https://api.validapay.com.br/v1/charges/pix","protocol":"https","host":["api","validapay","com","br"],"path":["v1","charges","pix"]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Wed, 19 Nov 2025 11:07:43 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"219"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"bcd7a225-a147-4f0c-a594-c64b808a2b6b"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"x-amz-apigw-id","value":"USa2yFyeIAMEJlA="},{"key":"X-Amzn-Trace-Id","value":"Root=1-691da4f7-293ea86f6afa9eac14e2b989;Parent=15f657aa9c3bc554;Sampled=0;Lineage=1:9b61c14c:0"}],"cookie":[],"body":"{\n    \"chargeId\": \"cha_1771511282731_9p1wo3tql\",\n    \"emv\": \"00020101021226910014br.gov.bcb.pix…\",\n    \"qrCode\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...\",\n    \"metadata\": {\n        \"orderId\": \"pedido-1001\"\n    }\n}"}]}]},{"name":"Split de pagamentos","item":[{"name":"Cobrança imediata com split","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[{"key":"","value":"","type":"text","disabled":true}],"body":{"mode":"raw","raw":"{\n    \"amount\": 1.00, \n    \"externalTxid\": \"loja-01-caixa-03\",\n    \"split\": [\n        {\n            \"type\": \"fixed\",\n            \"accountNumber\": \"896532569\", \n            \"amount\": 0.10\n        },\n        {\n            \"type\": \"fixed\",\n            \"accountNumber\": \"125485692\", \n            \"amount\": 0.10\n        }\n    ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/charges/pix","protocol":"https","host":["api","validapay","com","br"],"path":["v1","charges","pix"]},"description":"@scopes pix.cob/write\n\n@top\n\nCom esta funcionalidade você pode criar um QR Code de cobrança na sua conta e fazer split para outras contas ValidaPay.\n\n**Case de uso:**\n\n_Como SaaS, tenho parceiros/afiliados PF ou PJ. Quero gerar cobranças na minha conta preenchendo apenas o valor do produto e fazer split para as contas dos meus parceiros._\n\nUse `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `amount` | sim | Valor com precisão de duas casas decimais separado por ponto |\n| `externalTxid` | não | Identifica a loja, o caixa ou o vendedor responsável pela cobrança |\n| `type` | sim | Valor fixo ou porcentagem |"},"response":[{"name":"200","originalRequest":{"method":"POST","header":[{"key":"x-account-number","value":"428965347","type":"text"},{"key":"Origin","value":"{{ORIGIN}}","type":"text","disabled":true}],"url":{"raw":"https://api.validapay.com.br/v1/charges/pix","protocol":"https","host":["api","validapay","com","br"],"path":["v1","charges","pix"]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Wed, 19 Nov 2025 11:07:43 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"219"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"bcd7a225-a147-4f0c-a594-c64b808a2b6b"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"x-amz-apigw-id","value":"USa2yFyeIAMEJlA="},{"key":"X-Amzn-Trace-Id","value":"Root=1-691da4f7-293ea86f6afa9eac14e2b989;Parent=15f657aa9c3bc554;Sampled=0;Lineage=1:9b61c14c:0"}],"cookie":[],"body":"{\n    \"chargeId\": \"cha_1881511282731_9p1wo5plk\",\n    \"emv\": \"00020101021226910014br.gov.bcb.pix…\"\n}"}]},{"name":"Split para Conta Master","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[{"key":"X-Sub-Account","value":"{{subaccount_number}}","description":"  [REQUIRED] Subconta da cobrança","type":"text"}],"body":{"mode":"raw","raw":"{\n    \"amount\": 1.00, \n    \"externalTxid\": \"loja-01-caixa-03\",\n    \"split\": [\n        {\n            \"type\": \"fixed\",\n            \"amount\": 0.10\n        }\n    ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/charges/pix","protocol":"https","host":["api","validapay","com","br"],"path":["v1","charges","pix"]},"description":"@scopes pix.cob/write\n\n@top\n\nCom esta funcionalidade você pode criar um QR Code de cobrança na conta de um _Seller_ e fazer split para a sua conta.\n\n**Case de uso:**\n\n_Como SaaS tenho vários Sellers, cada um deles possui uma subconta ValidaPay. Quero gerar cobranças para qualquer subconta preenchendo apenas o valor do produto e fazer split para a minha conta Master_\n\n> ⚠️ **Atenção:** O número da subconta é retornado via webhook quando a subconta é aprovada.\n\nUse `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `amount` | sim | Valor com precisão de duas casas decimais separado por ponto |\n| `externalTxid` | não | Identifica a loja, o caixa ou o vendedor responsável pela cobrança |\n| `type` | sim | Valor fixo ou porcentagem |"},"response":[{"name":"200","originalRequest":{"method":"POST","header":[{"key":"x-account-number","value":"428965347","type":"text"},{"key":"Origin","value":"{{ORIGIN}}","type":"text","disabled":true}],"url":{"raw":"https://api.validapay.com.br/v1/charges/pix","protocol":"https","host":["api","validapay","com","br"],"path":["v1","charges","pix"]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Wed, 19 Nov 2025 11:07:43 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"219"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"bcd7a225-a147-4f0c-a594-c64b808a2b6b"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"x-amz-apigw-id","value":"USa2yFyeIAMEJlA="},{"key":"X-Amzn-Trace-Id","value":"Root=1-691da4f7-293ea86f6afa9eac14e2b989;Parent=15f657aa9c3bc554;Sampled=0;Lineage=1:9b61c14c:0"}],"cookie":[],"body":"{\n    \"chargeId\": \"cha_15631511282731_9p1wo5ghu\",\n    \"emv\": \"00020101021226910014br.gov.bcb.pix…\"\n}"}]},{"name":"Status de cobrança com split","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/charges/:chargeId//Identificador retornado no ato da geraçao da cobrança","protocol":"https","host":["api","validapay","com","br"],"path":["v1","charges",":chargeId","","Identificador retornado no ato da geraçao da cobrança"],"variable":[{"key":"chargeId","value":""}]},"description":"@scopes pix.cob/read\n\n@top"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{VALIDAPAY_PRD_URL}}/v1/charges/cha_1771453171013_fp6iocaxb//Retornado no ato da geração da cobrança","host":["{{VALIDAPAY_PRD_URL}}"],"path":["v1","charges","cha_1771453171013_fp6iocaxb","","Retornado no ato da geração da cobrança"]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Fri, 20 Feb 2026 12:15:57 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"425"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"b50b94d6-630e-4954-9180-01cc9ac260ae"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"ZFGDTFqwoAMEitg="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-6998507b-56448c8c14b81f674ce2d166;Parent=2c3092a237905812;Sampled=0;Lineage=1:d488af6c:0"}],"cookie":[],"body":"{\n    \"chargeId\": \"cha_1771453171013_fp6iocaxb\",\n    \"status\": \"PAID\",\n    \"amount\": 0.2,\n    \"paymentType\": \"PIX\",\n    \"masterAccointId\": \"2345567893\",\n    \"subaccountId\": \"987654322\",\n    \"emv\": \"00020101021226910014br.gov.bcb.pix…\",\n    \"paidAt\": \"2026-02-18T22:22:50.031Z\",\n    \"createdAt\": \"2026-02-18T22:19:31.013Z\"\n}"}]}]},{"name":"Subcontas ValidaPay","item":[{"name":"Criar subconta PF","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n    \"documentNumber\": \"11122233396\",\n    \"phoneNumber\": \"+5511912345678\",\n    \"email\": \"empresa@exemplo.com.br\",\n    \"motherName\": \"Teste Mãe\",\n    \"fullName\": \"Richard Feynman\",\n    \"socialName\": \"\",\n    \"birthDate\": \"31-12-2000\",\n    \"address\": {\n        \"postalCode\": \"06455030\",\n        \"street\": \"Alameda Xingu\",\n        \"number\": \"350\",\n        \"addressComplement\": \"\",\n        \"neighborhood\": \"Alphaville Industrial\",\n        \"city\": \"Barueri\",\n        \"state\": \"SP\"\n    },\n    \"isPoliticallyExposedPerson\": false,\n    \"financialDetails\": {\n        \"declaredIncome\": \"1DINP02\", \n        \"occupation\": \"ONP07\", \n        \"netWorth\": \"NWNP02\" \n    },\n    \"webhookUrl\": \"https://api.teste.com.br\" \n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/proposals","protocol":"https","host":["api","validapay","com","br"],"path":["v1","proposals"]},"description":"@scopes proposals/write\n\n@top\n\nCom esta funcionalidade você pode criar subcontas Pessoa Física na ValidaPay. Ao criar a subconta ela ficará associada à sua conta (chamaremos de conta Master).\n\nCase de uso:\n\n_Como SaaS tenho vários Sellers, preciso gerar cobranças para esses Sellers e receber split em cada venda._\n\n> ⚠️ **Atenção:** Não é possivel criar uma subconta com mesmo email e telefone da _master account._ \n  \n> ⚠️ **Atenção:** Dados de renda/faturamento no campo financialDetails são obrigatórios. Os respectivos códigos estão descritos no apêndice Campos Financeiros ao final da sessão Subcontas ValidaPay\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `documentNumber` | sim | CPF do titular |\n| `phoneNumber` | sim | Número de telefone do titular |\n| `email` | sim | email do titular |\n| `motherName` | sim |  |\n| `fullName` | sim | Nome completo do titular |\n| `socialName` | não |  |\n| `birthDate` | sim | Data de nascimento do titular |\n| `postalCode` | sim | CEP do titular |\n| `street` | sim |  |\n| `number` | sim |  |\n| `addressComplement` | sim |  |\n| `neighborhood` | sim |  |\n| `city` | sim |  |\n| `state` | sim |  |\n| `isPoliticallyExposedPerson` | sim |  |\n| `declaredIncome` | sim | Renda declarada do titular |\n| `occupation` | sim | Profissão do titular |\n| `netWorth` | sim | Patrimônio do titular |\n| `webhookUrl` | não | URL onde você gostaria de receber a notificação de criação de conta |"},"response":[{"name":"201","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n    \"documentNumber\": \"98765432100\",//required\n    \"phoneNumber\": \"+5511912345678\",//required\n    \"email\": \"cliente@exemplo.com.br\",//required\n    \"motherName\": \"Teste Mãe\",//required\n    \"fullName\": \"Teste teste\",//required\n    \"socialName\": \"\",//optional\n    \"birthDate\": \"31-12-2000\",//31-12-2000required\n    \"address\": {\n        \"postalCode\": \"\",//required\n        \"street\": \"Alameda Xingu\",//required\n        \"number\": \"12\",//required\n        \"addressComplement\": \"\",//required\n        \"neighborhood\": \"Alphaville Industrial\",//required\n        \"city\": \"Barueri\",//required\n        \"state\": \"SP\"//required\n    },//required\n    \"isPoliticallyExposedPerson\": false,//required\n    \"webhookUrl\": \"https://api.teste.com.br\"\n}\n","options":{"raw":{"language":"json"}}},"url":{"raw":"{{VALIDAPAY_DEV_URL}}/v1/proposals","host":["{{VALIDAPAY_DEV_URL}}"],"path":["v1","proposals"]}},"status":"Created","code":201,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Fri, 21 Nov 2025 21:52:49 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"114"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"95c3c9c8-bdff-431c-bf96-52cfbc649567"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"x-amz-apigw-id","value":"UafPnFnfGjQEDbg="},{"key":"X-Amzn-Trace-Id","value":"Root=1-6920df30-2d8a4cba2e6cd84a6ae6461a;Parent=7b7685dc5a72c677;Sampled=0;Lineage=1:1db5af2a:0"},{"key":"Access-Control-Allow-Credentials","value":"true"}],"cookie":[],"body":"{\n    \"status\": \"UNFINISHED\",\n    \"message\": \"Formulário criado com sucesso\",\n    \"formId\": \"a6358673-dd00-4c6d-9592-df393513a78a\"\n}"},{"name":"200","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n    \"documentNumber\": \"44455566619\",//required\n    \"phoneNumber\": \"+5511912345678\",//required\n    \"email\": \"cliente@exemplo.com.br\",//required\n    \"motherName\": \"Teste Mãe\",//required\n    \"fullName\": \"Teste teste\",//required\n    \"socialName\": \"\",//optional\n    \"birthDate\": \"31-12-2000\",//31-12-2000required\n    \"address\": {\n        \"postalCode\": \"06455030\",//required\n        \"street\": \"Alameda Xingu\",//required\n        \"number\": \"12\",//required\n        \"addressComplement\": \"\",//required\n        \"neighborhood\": \"Alphaville Industrial\",//required\n        \"city\": \"Barueri\",//required\n        \"state\": \"SP\"//required\n    },//required\n    \"isPoliticallyExposedPerson\": false,//required\n    \"webhookUrl\": \"https://api.teste.com.br\"\n}\n","options":{"raw":{"language":"json"}}},"url":{"raw":"{{VALIDAPAY_DEV_URL}}/v1/proposals","host":["{{VALIDAPAY_DEV_URL}}"],"path":["v1","proposals"]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Fri, 21 Nov 2025 21:38:31 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"116"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"e67b2b1d-4c17-4170-80b4-0c1e2ea8c553"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"x-amz-apigw-id","value":"UadITFwuGjQENvQ="},{"key":"X-Amzn-Trace-Id","value":"Root=1-6920dbce-0bf8d7f7196b865336885460;Parent=658d497510641612;Sampled=0;Lineage=1:1db5af2a:0"},{"key":"Access-Control-Allow-Credentials","value":"true"}],"cookie":[],"body":"{\n    \"status\": \"FINISHED\",\n    \"message\": \"Formulário atualizado com sucesso\",\n    \"formId\": \"cda0e605-44f7-4cbc-850c-ef3a2073c685\"\n}"}]},{"name":"Criar subconta PJ","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n    \"contactNumber\": \"+5511912345678\",\n    \"documentNumber\": \"99665544000130\",\n    \"businessEmail\": \"empresa@exemplo.com.br\",\n    \"businessName\": \"Empresa Exemplo LTDA\",\n    \"tradingName\": \"Empresa Exemplo\",\n    \"companyType\": \"PJ\",\n    \"owner\": [\n        {\n            \"ownerType\": \"SOCIO\",\n            \"documentNumber\": \"22233344405\",\n            \"fullName\": \"Cesar Lattes \",\n            \"phoneNumber\": \"+5511912345128\",\n            \"email\": \"socio@exemplo.com.br\",\n            \"motherName\": \"Marie Curie\",\n            \"socialName\": \"Nome\",\n            \"birthDate\": \"02-02-1990\",\n            \"address\": {\n                \"postalCode\": \"06455030\",\n                \"street\": \"Alameda Xingu\",\n                \"number\": \"50\",\n                \"addressComplement\": \"\",\n                \"neighborhood\": \"Alphaville Industrial\",\n                \"city\": \"Barueri\",\n                \"state\": \"SP\"\n            },\n            \"isPoliticallyExposedPerson\": false,\n            \"financialOwnerDetails\": {\n                \"ownerDeclaredIncome\": \"ODIB02\", \n                \"ownerDeclaredRevenue\": \"ODRB02\" \n              }\n        }\n    ],\n    \"businessAddress\": {\n        \"postalCode\": \"06455030\",\n        \"street\": \"Alamed Xingu\",\n        \"number\": \"350\",\n        \"addressComplement\": \"\",\n        \"neighborhood\": \"Alphaville Industrial\",\n        \"city\": \"Barueri\",\n        \"state\": \"SP\"\n    },\n    \"webhookUrl\": \"https://api.teste.com.br\" \n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/proposals","protocol":"https","host":["api","validapay","com","br"],"path":["v1","proposals"]},"description":"@scopes proposals/write\n\n@top\n\nCom esta funcionalidade você pode criar subcontas Pessoa Jurídica na ValidaPay. Ao criar a subconta ela ficará associada à sua conta (chamaremos de conta Master).\n\nCase de uso:\n\n_Como SaaS tenho vários Sellers, preciso gerar cobranças para esses Sellers e receber split em cada venda._\n\n> ⚠️ **Atenção:** Não é possivel criar uma subconta com mesmo email e telefone da _master account_ \n  \n> ⚠️ **Atenção:** Dados de renda/faturamento no campo financialDetails são obrigatórios. Os respectivos códigos estão descritos no apêndice Campos Financeiros ao final da sessão Subcontas ValidaPay\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `contactNumber` | sim | Telefone da empresa |\n| `documentNumber` | sim | CPF do sócio |\n| `businessEmail` | sim | email da empresa |\n| `businessName` | sim | Razão social |\n| `tradingName` | sim | Nome fantasia |\n| `companyType` | sim | PJ, MEI ou ME |\n| `ownerType` | sim |  |\n| `fullName` | sim | Nome completo do sócio |\n| `phoneNumber` | sim | Telefone celular do sócio |\n| `email` | sim | email do sócio |\n| `motherName` | sim |  |\n| `socialName` | sim |  |\n| `birthDate` | sim | Data de nascimento do sócio |\n| `postalCode` | sim | CEP da empresa |\n| `street` | sim |  |\n| `number` | sim |  |\n| `addressComplement` | sim |  |\n| `neighborhood` | sim |  |\n| `city` | sim |  |\n| `state` | sim |  |\n| `isPoliticallyExposedPerson` | sim |  |\n| `ownerDeclaredIncome` | sim | Renda do sócio |\n| `ownerDeclaredRevenue` | sim | Faturamento da empresa |\n| `webhookUrl` | não | URL onde você gostaria de receber a notificação de criação de conta |"},"response":[{"name":"201","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n    \"contactNumber\": \"+5511912345678\",//required\n    \"documentNumber\": \"99887766000105\",//required\n    \"businessEmail\": \"empresa@exemplo.com.br\",//required\n    \"businessName\": \"Empresa Exemplo LTDA\",//required\n    \"tradingName\": \"Empresa Exemplo\",//required\n    \"companyType\": \"PJ\",//required\n    \"owner\": [\n        {\n            \"ownerType\": \"SOCIO\",//required\n            \"documentNumber\": \"22233344405\",//required\n            \"fullName\": \"Cesar Lattes \",//required\n            \"phoneNumber\": \"+5511912345128\",//required\n            \"email\": \"socio@exemplo.com.br\",//required\n            \"motherName\": \"Marie Curie\",//required\n            \"socialName\": \"Nome\",//required\n            \"birthDate\": \"02-02-1990\",//required\n            \"address\": {\n                \"postalCode\": \"06455030\",//required\n                \"street\": \"Alameda Xingu\",//required\n                \"number\": \"50\",//required\n                \"addressComplement\": \"\",//optional\n                \"neighborhood\": \"Alphaville Industrial\",//required\n                \"city\": \"Barueri\",//required\n                \"state\": \"SP\"//required\n            },//required\n            \"isPoliticallyExposedPerson\": false//required\n        }\n    ],\n    \"businessAddress\": {\n        \"postalCode\": \"\",//required\n        \"street\": \"Alamed Xingu\",//required\n        \"number\": \"350\",//required\n        \"addressComplement\": \"\",//required\n        \"neighborhood\": \"Alphaville Industrial\",//required\n        \"city\": \"Barueri\",//required\n        \"state\": \"SP\"//required\n    }\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"{{VALIDAPAY_DEV_URL}}/v1/proposals","host":["{{VALIDAPAY_DEV_URL}}"],"path":["v1","proposals"]}},"status":"Created","code":201,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Fri, 21 Nov 2025 21:56:09 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"114"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"6e2c8256-8402-481b-bae3-5e4dcc796c2f"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"x-amz-apigw-id","value":"Uafu5EEdGjQEaCw="},{"key":"X-Amzn-Trace-Id","value":"Root=1-6920dff8-34a3f66b59d54085498a1aaa;Parent=215906c4b511cf7c;Sampled=0;Lineage=1:1db5af2a:0"},{"key":"Access-Control-Allow-Credentials","value":"true"}],"cookie":[],"body":"{\n    \"status\": \"UNFINISHED\",\n    \"message\": \"Formulário criado com sucesso\",\n    \"formId\": \"fb8cbb9d-d376-4604-940c-957e76e3dcbb\"\n}"},{"name":"200","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n   // \"clientCode\": \"a7e9ea3f-69e4-4599-92b4-6cb8a79c3512\", //código cliente\n    \"documentNumber\": \"11122233396\", //documento\n    \"phoneNumber\": \"+5511912345678\", // celular\n    \"email\": \"cliente@exemplo.com.br\", //email\n    \"motherName\": \"Teste Mãe\", //nome da mãe\n    \"fullName\": \"Teste teste\", //nome completo\n    \"socialName\": \"\", //nome social\n    \"birthDate\": \"31-12-2000\", //data de nascimento\n    \"address\": { //Endereço\n        \"postalCode\": \"06455030\", //CEP\n        \"street\": \"Alameda Xingu\", //Rua\n        \"number\": \"350\", //Número\n        \"addressComplement\": \"\", //Complemento\n        \"neighborhood\": \"Alphaville Industrial\", //Bairro\n        \"city\": \"Barueri\", //Cidade\n        \"state\": \"SP\" //Estado\n    },\n    \"isPoliticallyExposedPerson\": false, //Pessoa exposta politicamente\n    \"onboardingType\": \"BAAS\" //Tipo do Onboarding\n}\n","options":{"raw":{"language":"json"}}},"url":{"raw":"https://dev.validapay.com.br/proposals/form?eventType=create_or_update_form","protocol":"https","host":["dev","validapay","com","br"],"path":["proposals","form"],"query":[{"key":"eventType","value":"create_or_update_form"}]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Wed, 19 Nov 2025 10:38:34 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"117"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"94177e67-a74e-4e47-b59b-0a167669f947"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"x-amz-apigw-id","value":"USWlRGjUmjQERJQ="},{"key":"X-Amzn-Trace-Id","value":"Root=1-691d9e21-342cc18a725cebef5340a487;Parent=37de3f89754d1b61;Sampled=0;Lineage=1:11749300:0"}],"cookie":[],"body":"{\n    \"status\": \"FINISHED\",\n    \"message\": \"Formulário criado com sucesso\",\n    \"formId\": \"8f82a068-ff1a-45b7-8f98-71f07176e0dd\"\n}"}]},{"name":"Status de subconta","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/proposals/:formId//Identificador único retornado no ato do envio da proposta","protocol":"https","host":["api","validapay","com","br"],"path":["v1","proposals",":formId","","Identificador único retornado no ato do envio da proposta"],"variable":[{"key":"formId","value":""}]},"description":"@scopes proposals/write\n\n@botton  \nQuando a conta for aprovada, será enviado um evento na URL de webhook cadastrada nas rotas de criação de conta PF e PJ. O evento segue o seguinte layout:\n\n``` json\n{\n  \"event\": \"account_approved\",\n  \"status\": \"CONFIRMED\",\n  \"account\": {\n    \"account\": \"123456\",\n    \"branch\": \"0001\",\n    \"documentNumber\": \"123456789\",\n    \"ispb\": \"13935893\",\n    \"name\": \"Werner Heisenberg\"\n  },\n  \"onboardingId\": \"fc0e6dab-8210-4f2d-8fce-2e94990b63ef\",\n  \"documentNumber\": \"1234567889\",\n  \"formId\": \"7b83fcb4-fe9c-4ad3-8d3a-621fe9c9ffc1\",\n  \"createdAt\": \"2025-06-02T17:46:10.1120909\"\n}\n\n ```"},"response":[{"name":"PF 200","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{VALIDAPAY_DEV_URL}}/v1/proposals/a6358673-dd00-4c6d-9592-df393513a78a","host":["{{VALIDAPAY_DEV_URL}}"],"path":["v1","proposals","a6358673-dd00-4c6d-9592-df393513a78a"]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Fri, 21 Nov 2025 22:00:11 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"663"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"11987715-0281-4b3f-bcc8-cce56d13c1ca"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"x-amz-apigw-id","value":"UagUzGEKGjQEQOw="},{"key":"X-Amzn-Trace-Id","value":"Root=1-6920e0eb-74497348753b2c2a1626699b;Parent=6dbda9d34d8a3b91;Sampled=0;Lineage=1:1db5af2a:0"},{"key":"Access-Control-Allow-Credentials","value":"true"}],"cookie":[],"body":"{\n    \"phoneNumber\": \"+5511912345678\",\n    \"isPoliticallyExposedPerson\": false,\n    \"documentNumber\": \"98765432100\",\n    \"motherName\": \"Teste Mãe\",\n    \"fullName\": \"Teste teste\",\n    \"type\": \"PF\",\n    \"birthDate\": \"31-12-2000\",\n    \"email\": \"cliente@exemplo.com.br\",\n    \"socialName\": \"\",\n    \"address\": {\n        \"number\": \"12\",\n        \"addressComplement\": \"\",\n        \"city\": \"Barueri\",\n        \"street\": \"Alameda Xingu\",\n        \"postalCode\": \"\",\n        \"neighborhood\": \"Alphaville Industrial\",\n        \"state\": \"SP\"\n    },\n    \"metaData\": {\n        \"formId\": \"a6358673-dd00-4c6d-9592-df393513a78a\",\n        \"createdAt\": \"2025-11-21T21:52:49.155Z\",\n        \"updatedAt\": \"2025-11-21T21:53:43.213Z\"\n    },\n    \"proposalStatus\": {\n        \"form\": \"UNFINISHED\",\n        \"proposal\": \"PENDING\",\n        \"documents\": \"PENDING\",\n        \"urlDocumentscopy\": \"https://validapay.cadastro.io/0336bdddcd087923e2d0249b4cdd268d\"\n    }\n}"},{"name":"PJ 200","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{VALIDAPAY_SANDBOX_URL}}/v1/proposals/31aa2217-a149-40ba-847f-c23500a635c7","host":["{{VALIDAPAY_SANDBOX_URL}}"],"path":["v1","proposals","31aa2217-a149-40ba-847f-c23500a635c7"]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Tue, 24 Feb 2026 03:12:35 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"1275"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"d9d7deeb-f7d5-43cf-809d-a84b9f091c04"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"ZRCNPE4amjQERLQ="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-699d1721-45811ae8247c45814d5b5465;Parent=6e2611b448dc41b5;Sampled=0;Lineage=1:1db5af2a:0"}],"cookie":[],"body":"{\n    \"documentNumber\": \"99776655000113\",\n    \"type\": \"PJ\",\n    \"businessName\": \"FULANO SILVA PUBLICIDADE, PROMOCAO E PRODUCAO DE EVENTOS ESPORTIVOS LTDA\",\n    \"tradingName\": \"NEY SILVA\",\n    \"businessEmail\": \"titular@exemplo.com.br\",\n    \"contactNumber\": \"+558145630249\",\n    \"businessAddress\": {\n        \"number\": \"10\",\n        \"addressComplement\": \"CXPST 2\",\n        \"city\": \"CHA GRANDE\",\n        \"street\": \"ANTONIO\",\n        \"postalCode\": \"55636000\",\n        \"neighborhood\": \"CAMELA\",\n        \"state\": \"PE\"\n    },\n    \"financialCompanyDetails\": {\n        \"declaredCompanyRevenue\": \"DCRB02\"\n    },\n    \"owner\": [\n        {\n            \"ownerType\": \"SOCIO\",\n            \"address\": {\n                \"number\": \"10\",\n                \"city\": \"CHA GRANDE\",\n                \"street\": \"Av. Sao Jose\",\n                \"postalCode\": \"55636000\",\n                \"neighborhood\": \"Chã Grande\",\n                \"state\": \"PE\",\n                \"complement\": \"\"\n            },\n            \"financialOwnerDetails\": {\n                \"ownerDeclaredIncome\": \"ODIB04\"\n            },\n            \"phoneNumber\": \"+558112345689\",\n            \"isPoliticallyExposedPerson\": false,\n            \"documentNumber\": \"55566677720\",\n            \"motherName\": \"SELMA MARIA DA SILVA\",\n            \"fullName\": \"FUNANO CRISTOVAO DA SILVA\",\n            \"type\": \"PF\",\n            \"birthDate\": \"30-11-1991\",\n            \"email\": \"contato@exemplo.com.br\"\n        }\n    ],\n    \"proposalId\": \"d0c39afa-d034-4330-8d57-527eacca88c6\",\n    \"metaData\": {\n        \"formId\": \"31aa2217-a149-40ba-847f-c23500a635c7\",\n        \"createdAt\": \"2026-02-24T02:18:55.257Z\",\n        \"updatedAt\": \"2026-02-24T02:29:04.911Z\",\n        \"origin\": \"API\"\n    },\n    \"proposalStatus\": {\n        \"form\": \"FINISHED\",\n        \"sendStatus\": \"SENT\",\n        \"proposal\": \"PENDING\",\n        \"documents\": \"PENDING\",\n        \"urlDocumentscopy\": null\n    }\n}"}]},{"name":"Listar subcontas","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[{"key":"","value":"","type":"text","disabled":true}],"body":{"mode":"raw","raw":"{\n    \"amount\": 1.00, \n    \"split\": [\n        {\n            \"type\": \"fixed\",\n            \"amount\": 0.10\n        }\n    ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/accounts/subaccounts?dateFrom=2026-02-01T00:00:00.000Z&dateTo=2026-02-23T23:59:59.999Z&page=1&perPage=15","protocol":"https","host":["api","validapay","com","br"],"path":["v1","accounts","subaccounts"],"query":[{"key":"dateFrom","value":"2026-02-01T00:00:00.000Z"},{"key":"dateTo","value":"2026-02-23T23:59:59.999Z"},{"key":"page","value":"1"},{"key":"perPage","value":"15"}]},"description":"@scopes subaccounts/read\n\n@top\n\nCom esta rota você poderá listar todas as subcontas associadas à sua _master account_\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `amount` | sim | Valor com precisão de duas casas decimais separado por ponto |\n| `type` | sim | Valor fixo ou porcentagem |"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{VALIDAPAY_SANDBOX_URL}}/v1/accounts/subaccounts?dateFrom=2026-02-01T00:00:00.000Z&dateTo=2026-02-23T23:59:59.999Z&page=1&perPage=15","host":["{{VALIDAPAY_SANDBOX_URL}}"],"path":["v1","accounts","subaccounts"],"query":[{"key":"dateFrom","value":"2026-02-01T00:00:00.000Z"},{"key":"dateTo","value":"2026-02-23T23:59:59.999Z"},{"key":"page","value":"1"},{"key":"perPage","value":"15"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Tue, 24 Feb 2026 02:36:01 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"688"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"e3a7ecba-e4dd-42c5-8c38-792b12a3648a"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"ZQ82fE9NmjQEQLw="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-699d0e8f-7f655341711ea7640a062b46;Parent=4a5ea9b80256037b;Sampled=0;Lineage=1:7493be8a:0"}],"cookie":[],"body":"{\n    \"masterAccountId\": \"SANDBOX_0438f4c8-0031-7051-16d4-5a23704756b6\",\n    \"subAccounts\": [\n        {\n            \"documentNumber\": \"66677788830\",\n            \"createdAt\": \"2026-02-23T22:29:52.537Z\",\n            \"accountNumber\": \"4960589\",\n            \"status\": \"CONFIRMED\",\n            \"onboardingId\": \"b9790268-a770-4aec-8fe5-d891f17e8007\",\n            \"name\": \"Friedrich Nietzsche\",\n            \"dailyWithdrawalLimit\": 3000,\n            \"balance\": 0\n        },\n        {\n            \"documentNumber\": \"33344455508\",\n            \"createdAt\": \"2026-02-17T20:38:45.664Z\",\n            \"accountNumber\": \"4949228\",\n            \"status\": \"CONFIRMED\",\n            \"onboardingId\": \"30608b18-7258-437d-a6cb-63e5882e4fb7\",\n            \"name\": \"Tales de Mileto\",\n            \"dailyWithdrawalLimit\": 3000,\n            \"balance\": 170.9\n        }\n    ],\n    \"page\": 1,\n    \"perPage\": 15,\n    \"hasMore\": false,\n    \"dateFrom\": \"2026-02-01T00:00:00.000Z\",\n    \"dateTo\": \"2026-02-23T23:59:59.999Z\"\n}"}]},{"name":"Listar cobranças","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[{"key":"X-Sub-Account","value":"{{subaccount_number}}","description":"  [REQUIRED] Subconta da qual você quer listar as cobranças","type":"text"}],"url":{"raw":"https://api.validapay.com.br/v1/charges?dateFrom=2026-02-01T00:00:00.000Z&dateTo=2026-02-23T23:59:59.999Z&page=1&perPage=15","protocol":"https","host":["api","validapay","com","br"],"path":["v1","charges"],"query":[{"key":"dateFrom","value":"2026-02-01T00:00:00.000Z"},{"key":"dateTo","value":"2026-02-23T23:59:59.999Z"},{"key":"page","value":"1"},{"key":"perPage","value":"15"}]},"description":"@scopes subaccounts/read\n\n@top\n\nCom esta rota você poderá listar todas as cobranças que a sua _master account_ gerou em uma subcontas"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[{"key":"X-Sub-Account","value":"4949228","type":"text"}],"url":{"raw":"{{VALIDAPAY_SANDBOX_URL}}/v1/charges?dateFrom=2026-02-01T00:00:00.000Z&dateTo=2026-02-23T23:59:59.999Z&page=1&perPage=15","host":["{{VALIDAPAY_SANDBOX_URL}}"],"path":["v1","charges"],"query":[{"key":"dateFrom","value":"2026-02-01T00:00:00.000Z"},{"key":"dateTo","value":"2026-02-23T23:59:59.999Z"},{"key":"page","value":"1"},{"key":"perPage","value":"15"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Tue, 24 Feb 2026 03:05:52 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"8063"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"e41da75f-5612-4e29-ba6f-57087620e05f"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"ZRBOEHNumjQEFTQ="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-699d158c-6792cb75331afe7912fee923;Parent=270283094e3659dd;Sampled=0;Lineage=1:c2dfeee2:0"}],"cookie":[],"body":"{\n    \"data\": [\n        {\n            \"status\": \"PENDING\",\n            \"createdAt\": \"2026-02-23T18:46:22.652Z\",\n            \"chargeId\": \"cha_1771872382645_qe5j0ohge\",\n            \"updatedAt\": \"2026-02-23T18:46:22.652Z\",\n            \"masterAccountId\": \"SANDBOX_0438f4c8-0031-7051-16d4-5a23704756b6\",\n            \"amount\": 39.9,\n            \"attempts\": 1,\n            \"emvQrCode\": \"00020101021226930014br.gov.bcb.pix…\",\n            \"paymentType\": \"PIX\",\n            \"subAccountId\": \"4949228\"\n        },\n        {\n            \"status\": \"PENDING\",\n            \"createdAt\": \"2026-02-23T18:34:13.130Z\",\n            \"chargeId\": \"cha_1771871653130_pzzsyzeha\",\n            \"updatedAt\": \"2026-02-23T18:34:13.130Z\",\n            \"masterAccountId\": \"SANDBOX_0438f4c8-0031-7051-16d4-5a23704756b6\",\n            \"amount\": 39.9,\n            \"attempts\": 1,\n            \"emvQrCode\": \"00020101021226930014br.gov.bcb.pix…\",\n            \"paymentType\": \"PIX\",\n            \"subAccountId\": \"4949228\"\n        },\n        {\n            \"status\": \"PENDING\",\n            \"createdAt\": \"2026-02-23T18:34:09.892Z\",\n            \"chargeId\": \"cha_1771871649852_mm0luemzr\",\n            \"updatedAt\": \"2026-02-23T18:34:09.892Z\",\n            \"masterAccountId\": \"SANDBOX_0438f4c8-0031-7051-16d4-5a23704756b6\",\n            \"amount\": 39.9,\n            \"attempts\": 1,\n            \"emvQrCode\": \"00020101021226930014br.gov.bcb.pix…\",\n            \"paymentType\": \"PIX\",\n            \"subAccountId\": \"4949228\"\n        }\n    ],\n    \"totalItems\": 23,\n    \"totalPages\": 2,\n    \"page\": 1,\n    \"limit\": 15,\n    \"dateFrom\": \"2026-02-01T00:00:00.000Z\",\n    \"dateTo\": \"2026-02-23T23:59:59.999Z\"\n}"}]},{"name":"Saldo subcontas","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/balance?accountId=9489623","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","balance"],"query":[{"key":"accountId","value":"9489623","description":"[REQUIRED] Número da subconta. Para consultar o saldo de várias subcontas envie separado por virgula"}]},"description":"@scopes wallet/read\n\n@top\n\nCom esta funcionalidade você pode verificar o saldo de uma ou várias subcontas\n\n> ⚠️ **Atenção:** Para consultar o saldo de várias subcontas envie o header acoountId com o número das subcontas separado por vírgula, por exemplo: 9489623,9489624,9489625"},"response":[{"name":"Sucesso","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/balance?accountId=459013777,46085168","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","balance"],"query":[{"key":"accountId","value":"459013777,46085168"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Tue, 17 Mar 2026 03:44:35 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"209"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"264231f5-a8b3-4011-9d1f-8839c4a71041"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"aWUljHT4oAMEpqQ="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-69b8ce23-78642bd50fcf3e250b8e1df6;Parent=677ba3daa288157b;Sampled=0;Lineage=1:133a49a5:0"}],"cookie":[],"body":"{\n    \"masterAccountId\": \"429131313\",\n    \"balances\": [\n        {\n            \"accountNumber\": \"459013888\",\n            \"name\": \"VALIDAPAY PAGAMENTOS TECNOLOGIA E SERVICOS\",\n            \"balance\": 54.81\n        },\n        {\n            \"accountNumber\": \"460851986\",\n            \"name\": \"VALIDA PIX\",\n            \"balance\": 196.82\n        }\n    ]\n}"},{"name":"Acesso negado","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/balance?accountId=436514888","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","balance"],"query":[{"key":"accountId","value":"436514888"}]}},"status":"Unauthorized","code":401,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Tue, 17 Mar 2026 03:45:53 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"162"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"1b9dfcbc-9380-466a-bf99-8d5143480bb4"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"aWUxzHGCIAMEYYw="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-69b8ce71-0eb1e72c692cf3921f86ab00;Parent=115a0d6a059ae83e;Sampled=0;Lineage=1:133a49a5:0"}],"cookie":[],"body":"{\n    \"error\": {\n        \"message\": \"Subconta 436514888 nao pertence a esta conta master\",\n        \"code\": \"UNAUTHORIZED_SUBACCOUNT\",\n        \"details\": null,\n        \"timestamp\": \"2026-03-17T03:45:53.738Z\"\n    }\n}"},{"name":"Subconta não encontrada","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/balance?accountId=459013666","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","balance"],"query":[{"key":"accountId","value":"459013666"}]}},"status":"Not Found","code":404,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Tue, 17 Mar 2026 03:46:49 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"140"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"811b8fb2-09fd-4760-90dc-f7f0d37f6533"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"aWU6iH8YoAMERhg="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-69b8cea9-28d5bace7a4a8bae735d35dc;Parent=2f5bc952fdf041fb;Sampled=0;Lineage=1:133a49a5:0"}],"cookie":[],"body":"{\n    \"error\": {\n        \"message\": \"Subconta 459013666 nao encontrada\",\n        \"code\": \"SUBACCOUNT_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-03-17T03:46:49.577Z\"\n    }\n}"}]}]},{"name":"Produtos","item":[{"name":"Criar Produto","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"url":{"raw":"https://api.validapay.com.br/v1/products","protocol":"https","host":["api","validapay","com","br"],"path":["v1","products"]},"description":"@scopes products/write\n\n@top\n\nCria um novo produto ou serviço com nome, descrição, preço e configurações de recorrência.\n\nOs produtos criados ficam disponíveis no painel administrativo e podem ser utilizados tanto no checkout transparente (via API) quanto no checkout pro (link de pagamento).\n\nTipos de recorrência em prices[].recurrenceType:\n\n- ONE_TIME → Avulsa\n- WEEKLY → Semanal\n- MONTHLY → Mensal\n- QUARTERLY → Trimestral\n- SEMIANNUAL → Semestral\n- YEARLY → Anual\n\nCase de uso:\n\n_Como SaaS, quero cadastrar meus planos como produtos com preços recorrentes, para que meus clientes possam assinar diretamente pelo checkout pro ou pela minha própria interface._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `name` | sim | Nome do produto |\n| `description` | não |  |\n| `type` | não | RECURRING ou ONE_TIME (default RECURRING) |\n| `statementDescriptor` | não | max 22 caracteres |\n| `isActive` | não |  |\n| `prices` | sim |  |\n| `prices.title` | sim |  |\n| `prices.amount` | sim | Valor em reais (> 0) |\n| `prices.currency` | não |  |\n| `prices.recurrenceType` | sim | WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL, YEARLY ou ONE_TIME |\n| `prices.recurrenceInterval` | não | min 1 (ex: 2 = bimestral) |\n| `prices.trialDays` | não |  |\n| `prices.compareAtPrice` | não | Preço \"de\" |","body":{"mode":"raw","raw":"{\n  \"name\": \"Plano Premium\",\n  \"description\": \"Acesso completo à plataforma\",\n  \"type\": \"RECURRING\",\n  \"statementDescriptor\": \"VALIDAPAY PREMIUM\",\n  \"isActive\": true,\n  \"metadata\": {},\n  \"prices\": [\n    {\n      \"title\": \"Mensal\",\n      \"amount\": 99.9,\n      \"currency\": \"BRL\",\n      \"recurrenceType\": \"MONTHLY\",\n      \"recurrenceInterval\": 1,\n      \"trialDays\": 7,\n      \"compareAtPrice\": 129.9\n    },\n    {\n      \"title\": \"Anual\",\n      \"amount\": 899.0,\n      \"currency\": \"BRL\",\n      \"recurrenceType\": \"YEARLY\",\n      \"recurrenceInterval\": 1\n    }\n  ]\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"productId\": \"prod_xxx\",\n  \"name\": \"Plano Premium\",\n  \"prices\": [\n    {\n      \"priceId\": \"price_xxx\",\n      \"amount\": 99.9,\n      \"checkoutUrl\": \"https://app.validapay.com.br/pagamento/pl_xxx\"\n    }\n  ]\n}","cookie":[]},{"name":"400","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"O campo name é obrigatório\",\n        \"code\": \"INVALID_PRODUCT_DATA\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Listar Produtos","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/products?limit=50&lastKey=&status=&search=","protocol":"https","host":["api","validapay","com","br"],"path":["v1","products"],"query":[{"key":"limit","value":"50","description":"Quantidade de itens por página (default 50) - optional","disabled":false},{"key":"lastKey","value":"","description":"base64 - optional","disabled":false},{"key":"status","value":"","description":"active | inactive - optional","disabled":false},{"key":"search","value":"","description":"busca por nome - optional","disabled":false}]},"description":"@scopes products/read\n\n@top\n\n\n\nLista todos os produtos cadastrados com suporte a filtros por status e paginação."},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"items\": [\n    {\n      \"productId\": \"prod_xxx\",\n      \"name\": \"Plano Premium\"\n    }\n  ],\n  \"pagination\": {\n    \"total\": 10,\n    \"hasMore\": false,\n    \"lastKey\": null\n  }\n}","cookie":[]}]},{"name":"Buscar Produto","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/products/:id","protocol":"https","host":["api","validapay","com","br"],"path":["v1","products",":id"],"variable":[{"key":"id","value":"prod_xxx"}]},"description":"@scopes products/read\n\n@top\n\n\n\nRetorna todos os detalhes de um produto específico, incluindo preço e configurações."},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"productId\": \"prod_xxx\",\n  \"name\": \"Plano Premium\",\n  \"prices\": [\n    {\n      \"priceId\": \"price_xxx\",\n      \"amount\": 99.9\n    }\n  ]\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Produto não encontrado\",\n        \"code\": \"PRODUCT_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Atualizar Produto","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"PUT","header":[],"url":{"raw":"https://api.validapay.com.br/v1/products/:id","protocol":"https","host":["api","validapay","com","br"],"path":["v1","products",":id"],"variable":[{"key":"id","value":"prod_xxx"}]},"description":"@scopes products/write\n\n@top\n\n\n\nAtualiza as informações de um produto, como nome, descrição ou preço.\nMesmos campos de POST (todos opcionais). Para atualizar preço existente, inclua `priceId` no item de `prices[]`.\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `name` | não |  |\n| `description` | não |  |\n| `type` | não |  |\n| `statementDescriptor` | não |  |\n| `isActive` | não |  |\n| `prices` | não | Para atualizar preço existente, inclua priceId no item |\n| `prices.priceId` | não | ID do preço existente |\n| `prices.amount` | não |  |\n| `prices.recurrenceType` | não |  |\n| `prices.recurrenceInterval` | não |  |\n| `prices.trialDays` | não |  |\n| `prices.compareAtPrice` | não |  |\n| `prices.title` | não | Novo preço |","body":{"mode":"raw","raw":"{\n  \"name\": \"Plano Premium Plus\",\n  \"description\": \"Acesso completo à plataforma\",\n  \"type\": \"RECURRING\",\n  \"statementDescriptor\": \"VALIDAPAY PREMIUM\",\n  \"isActive\": true,\n  \"metadata\": {},\n  \"prices\": [\n    {\n      \"priceId\": \"price_xxx\",\n      \"amount\": 109.9,\n      \"recurrenceType\": \"MONTHLY\",\n      \"recurrenceInterval\": 1,\n      \"trialDays\": 7,\n      \"compareAtPrice\": 129.9\n    },\n    {\n      \"title\": \"Trimestral\",\n      \"amount\": 279.0,\n      \"recurrenceType\": \"QUARTERLY\",\n      \"recurrenceInterval\": 1\n    }\n  ]\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"productId\": \"prod_xxx\",\n  \"name\": \"Plano Premium Plus\",\n  \"newPrices\": [\n    {\n      \"priceId\": \"price_yyy\"\n    }\n  ]\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Produto não encontrado\",\n        \"code\": \"PRODUCT_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Remover Produto","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"DELETE","header":[],"url":{"raw":"https://api.validapay.com.br/v1/products/:id","protocol":"https","host":["api","validapay","com","br"],"path":["v1","products",":id"],"variable":[{"key":"id","value":"prod_xxx"}]},"description":"@scopes products/write\n\n@top\n\n\n\nRemove um produto que não esteja vinculado a assinaturas ativas."},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"deleted\": true,\n  \"productId\": \"prod_xxx\"\n}","cookie":[]},{"name":"400","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Não é possível deletar um produto que possui assinaturas vinculadas\",\n        \"code\": \"PRODUCT_HAS_SUBSCRIPTIONS\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Produto não encontrado\",\n        \"code\": \"PRODUCT_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Arquivar Produto","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"url":{"raw":"https://api.validapay.com.br/v1/products/:id/archive","protocol":"https","host":["api","validapay","com","br"],"path":["v1","products",":id","archive"],"variable":[{"key":"id","value":"prod_xxx"}]},"description":"@scopes products/write\n\n@top\n\n\n\nGuarda o produto sem excluí-lo, mantendo o histórico de cobranças vinculadas."},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"productId\": \"prod_xxx\",\n  \"archivedAt\": \"2024-01-20T10:00:00Z\",\n  \"checkoutsDeactivated\": 3\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Produto não encontrado\",\n        \"code\": \"PRODUCT_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]}]},{"name":"Links de pagamento","item":[{"name":"Criar link de pagamento","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"https://api.validapay.com.br/v1/checkouts","protocol":"https","host":["api","validapay","com","br"],"path":["v1","checkouts"]},"description":"@scopes checkouts/write\n\n@top\n\nCria uma página de pagamento (payment link) configurável, com produtos, formas de pagamento aceitas, cupons e aparência personalizada. O link é reutilizável e não fica vinculado a um cliente específico.\n\nÉ obrigatório informar `priceId` (preço já cadastrado) ou `product` (produto com preços inline).\n\nFormas de pagamento suportadas: pix, creditcard, boleto e pix_automatico.\n\n**Pix Automático** está disponível apenas para **contas PJ** (conta ValidaPay cadastrada com CNPJ) e só é aceito em preços recorrentes (`recurrenceType` WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL ou YEARLY). O cliente autoriza a recorrência uma única vez no aplicativo do banco e as cobranças seguintes são debitadas automaticamente, sem novo QR Code a cada ciclo. Até o banco do pagador confirmar a autorização, a assinatura fica com status `PENDING`.\n\nO valor mínimo por cobrança é de **R$ 4,99**.\n\nErros: `400 PIX_AUTOMATICO_PJ_ONLY` (conta PF) e `400 PIX_AUTOMATICO_MIN_AMOUNT` (valor abaixo do mínimo).\n\nAo informar `termsOfServiceUrl` e/ou `privacyPolicyUrl`, o checkout exibe um aceite obrigatório com os links: o cliente só consegue finalizar a compra depois de marcar que leu e concorda. O texto do aceite se adapta a um ou aos dois links. Sem esses campos, nenhum aceite é exibido.\n\nCase de uso:\n\n_Como SaaS, quero criar um link de pagamento reutilizável para uma oferta — definindo cores, parcelamento e order bumps — e compartilhá-lo com vários clientes._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `priceId` | sim | ID do preço já cadastrado (obrigatório priceId OU product) |\n| `allowedPaymentMethods` | sim | Formas de pagamento aceitas: pix, creditcard, boleto, pix_automatico (só conta PJ, em preço recorrente) |\n| `successUrl` | não | Redireciona após pagamento aprovado |\n| `cancelUrl` | não | Redireciona ao cancelar |\n| `redirectAfterPaymentUrl` | não | URL de redirecionamento pós-pagamento |\n| `termsOfServiceUrl` | não | Termos de serviço exibidos no checkout para aceite do cliente |\n| `privacyPolicyUrl` | não | Política de privacidade exibida no checkout para aceite do cliente |\n| `successMessage` | não | Mensagem exibida após o pagamento |\n| `maxInstallments` | não | Limite de parcelas (1 a 12) |\n| `freeInstallments` | não | Parcelas sem juros (1 a 12, default 1) |\n| `passFeesToCustomer` | não | Repassa as taxas ao cliente (default false) |\n| `checkoutName` | não | Nome interno do checkout |\n| `primaryColor` | não | Cor primária em hex |\n| `secondaryColor` | não | Cor secundária em hex |\n| `fontColor` | não | Cor do texto em hex |\n| `showProductImage` | não | Exibir imagem do produto (default true) |\n| `orderBumps` | não | Produtos adicionais oferecidos no checkout |\n| `orderBumps.priceId` | sim | priceId do produto adicional |\n| `orderBumps.label` | não | Texto exibido |\n| `orderBumps.displayMode` | não | Modo de exibição |","body":{"mode":"raw","raw":"{\n  \"priceId\": \"price_xxx\",\n  \"allowedPaymentMethods\": [\n    \"pix\",\n    \"creditcard\",\n    \"boleto\",\n    \"pix_automatico\"\n  ],\n  \"successUrl\": \"https://meusite.com/obrigado\",\n  \"cancelUrl\": \"https://meusite.com/cancelado\",\n  \"redirectAfterPaymentUrl\": \"https://meusite.com/redirect\",\n  \"termsOfServiceUrl\": \"https://meusite.com/termos-de-servico\",\n  \"privacyPolicyUrl\": \"https://meusite.com/politica-de-privacidade\",\n  \"successMessage\": \"Obrigado pela compra!\",\n  \"maxInstallments\": 12,\n  \"freeInstallments\": 1,\n  \"passFeesToCustomer\": false,\n  \"checkoutName\": \"Oferta Black Friday\",\n  \"primaryColor\": \"#7C3AED\",\n  \"secondaryColor\": \"#EDE9FE\",\n  \"fontColor\": \"#1F2937\",\n  \"showProductImage\": true,\n  \"metadata\": {},\n  \"orderBumps\": [\n    {\n      \"priceId\": \"price_yyy\",\n      \"label\": \"Adicionar suporte premium\",\n      \"displayMode\": \"checkbox\"\n    }\n  ]\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"pl_xxx\",\n  \"url\": \"https://app.validapay.com.br/pagamento/pl_xxx\",\n  \"priceId\": \"price_xxx\"\n}","cookie":[]}]},{"name":"Listar links de pagamento","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/checkouts?limit=15&lastKey=&status=&search=","protocol":"https","host":["api","validapay","com","br"],"path":["v1","checkouts"],"query":[{"key":"limit","value":"15","description":"Quantidade de itens por página (default 15) - optional","disabled":false},{"key":"lastKey","value":"","description":"base64 - optional","disabled":false},{"key":"status","value":"","description":"Filtra por status do checkout - optional","disabled":false},{"key":"search","value":"","description":"Busca por texto - optional","disabled":false}]},"description":"@scopes checkouts/read\n\n@top\n\nLista todas as páginas de pagamento (checkouts) criadas, com seus status e configurações. Suporta paginação e filtros por status e busca textual."},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"items\": [\n    {\n      \"id\": \"pl_xxx\",\n      \"url\": \"https://app.validapay.com.br/pagamento/pl_xxx\"\n    }\n  ],\n  \"pagination\": {\n    \"total\": 5,\n    \"hasMore\": false\n  }\n}","cookie":[]}]},{"name":"Buscar link de pagamento","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/checkouts/:id","protocol":"https","host":["api","validapay","com","br"],"path":["v1","checkouts",":id"],"variable":[{"key":"id","value":"pl_xxx","description":"ID do checkout / payment link (ex: pl_xxx) - required"}]},"description":"@scopes checkouts/read\n\n@top\n\nRetorna os detalhes completos de uma página de pagamento, incluindo produtos e formas de pagamento aceitas.\n\nO identificador aceita diferentes prefixos: `cha_` (cobrança), `cs_` (sessão), `price_` (preço) e `pl_` (payment link). A autenticação é opcional — o checkout pode ser consultado publicamente."},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"pl_xxx\",\n  \"status\": \"ACTIVE\",\n  \"priceId\": \"price_xxx\"\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Checkout não encontrado\",\n        \"code\": \"CHECKOUT_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Atualizar link de pagamento","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"PUT","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"https://api.validapay.com.br/v1/checkouts/:id","protocol":"https","host":["api","validapay","com","br"],"path":["v1","checkouts",":id"],"variable":[{"key":"id","value":"pl_xxx","description":"ID do checkout / payment link (ex: pl_xxx) - required"}]},"description":"@scopes checkouts/write\n\n@top\n\nAtualiza as configurações de uma página de pagamento, como preço vinculado, parcelamento ou aparência. Todos os campos são opcionais — envie apenas o que deseja alterar.\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `priceId` | não | Novo preço vinculado ao checkout |\n| `maxInstallments` | não | Limite de parcelas (1 a 12) |\n| `primaryColor` | não | Cor primária em hex |\n| `showProductImage` | não | Exibir imagem do produto |\n| `termsOfServiceUrl` | não | Termos de serviço exibidos no checkout para aceite do cliente |\n| `privacyPolicyUrl` | não | Política de privacidade exibida no checkout para aceite do cliente |\n| `applyBrandingToAllPrices` | não | Aplica a identidade visual a todos os preços |","body":{"mode":"raw","raw":"{\n  \"priceId\": \"price_yyy\",\n  \"discounts\": [],\n  \"maxInstallments\": 6,\n  \"primaryColor\": \"#FF0000\",\n  \"showProductImage\": false,\n  \"termsOfServiceUrl\": \"https://meusite.com/termos-de-servico\",\n  \"privacyPolicyUrl\": \"https://meusite.com/politica-de-privacidade\",\n  \"applyBrandingToAllPrices\": true\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"pl_xxx\",\n  \"priceId\": \"price_yyy\"\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Checkout não encontrado\",\n        \"code\": \"CHECKOUT_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Criar sessão de pagamento","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"https://api.validapay.com.br/v1/checkout-sessions","protocol":"https","host":["api","validapay","com","br"],"path":["v1","checkout-sessions"]},"description":"@scopes checkouts/write\n\n@top\n\nCria um acesso temporário e seguro a uma página de pagamento, com cliente e configurações pré-preenchidos. É de uso único: expira após o pagamento.\n\nInforme o `priceId` de um preço já cadastrado. Opcionalmente, envie os dados do cliente, restrinja as formas de pagamento e personalize a aparência.\n\nA resposta inclui o `id` da sessão e a `url` de pagamento hospedada pela ValidaPay.\n\nFormas de pagamento aceitas em `allowedPaymentMethods`: pix, creditcard, boleto e pix_automatico. O **Pix Automático** está disponível apenas para **contas PJ** (conta ValidaPay cadastrada com CNPJ) e exige um preço recorrente (`recurrenceType` WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL ou YEARLY): o cliente autoriza a recorrência uma única vez no aplicativo do banco e os ciclos seguintes são debitados automaticamente. Enquanto a autorização não é confirmada pelo banco do pagador, a assinatura fica com status `PENDING`. O valor mínimo por cobrança é de **R$ 4,99**.\n\nErros: `400 PIX_AUTOMATICO_PJ_ONLY` (conta PF) e `400 PIX_AUTOMATICO_MIN_AMOUNT` (valor abaixo do mínimo).\n\nAo informar `termsOfServiceUrl` e/ou `privacyPolicyUrl`, o checkout exibe um aceite obrigatório com os links: o cliente só consegue finalizar a compra depois de marcar que leu e concorda. O texto do aceite se adapta a um ou aos dois links. Sem esses campos, nenhum aceite é exibido.\n\nCase de uso:\n\n_Como SaaS, quero gerar um link de pagamento nominal para cada cliente no momento da contratação, com uso único para evitar cobranças duplicadas._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `priceId` | sim | Preço da sessão (deve começar com price_) |\n| `allowedPaymentMethods` | não | Métodos exibidos: pix, creditcard, boleto, pix_automatico (só conta PJ; omitir usa o padrão do price) |\n| `customer` | não | Pré-preenche os dados do cliente no checkout |\n| `customer.name` | não | Nome exibido |\n| `customer.email` | não | Usado para localizar cliente existente |\n| `customer.documentNumber` | não | CPF (11) ou CNPJ (14 dígitos) |\n| `customer.phone` | não | Telefone |\n| `customer.address` | não | Endereço (obrigatório para boleto no pagamento) |\n| `customer.address.type` | não | Tipo do endereço |\n| `customer.address.street` | não |  |\n| `customer.address.number` | não |  |\n| `customer.address.complement` | não |  |\n| `customer.address.neighborhood` | não |  |\n| `customer.address.city` | não |  |\n| `customer.address.state` | não |  |\n| `customer.address.zipCode` | não |  |\n| `customer.address.country` | não |  |\n| `customer.address.cityCode` | não | Código IBGE (necessário para nota fiscal) |\n| `items` | não | Lista de { priceId, quantity } (sobrescreve o item principal) |\n| `items.priceId` | sim | priceId do item |\n| `items.quantity` | não | Quantidade (default 1) |\n| `billingDay` | não | Dia do mês das cobranças recorrentes (1 a 31) |\n| `prorataStartDate` | não | Início do cálculo de pró-rata (YYYY-MM-DD) |\n| `installments` | não | Parcelas fixas da sessão (1 a 12) |\n| `dueDate` | não | Vencimento do boleto (YYYY-MM-DD, maior que hoje) |\n| `boletoDueDays` | não | Dias até o vencimento (mín. 1; ignorado se dueDate informado) |\n| `expirationAfterDueDate` | não | Dias após o vencimento que o boleto aceita pagamento (0 a 60) |\n| `discounts` | não | Descontos aplicados à sessão |\n| `discounts.type` | sim | PERCENTAGE ou FIXED |\n| `discounts.value` | sim | Valor do desconto |\n| `discounts.paymentMethod` | não | Restringe a um método |\n| `discounts.fromCycle` | não | Ciclo inicial |\n| `discounts.toCycle` | não | Ciclo final |\n| `discounts.durationMonths` | não | Duração em meses |\n| `passFeesToCustomer` | não | Repassa as taxas ao cliente (default false) |\n| `freeInstallments` | não | Parcelas sem juros (1 a 12, default 1) |\n| `maxInstallments` | não | Limite máximo de parcelas exibido (1 a 12) |\n| `boletoInstructions` | não | Regras de multa/juros/desconto do boleto |\n| `boletoInstructions.fine` | não | Multa em % (0.1 a 100; fine + interest <= 60) |\n| `boletoInstructions.interest` | não | Juros mensais em % (0.1 a 100) |\n| `boletoInstructions.discount` | não | Desconto antecipado |\n| `boletoInstructions.discount.amount` | não | Valor do desconto |\n| `boletoInstructions.discount.modality` | não | fixed (R$) ou percent (%) |\n| `boletoInstructions.discount.limitDate` | não | Data limite (antes de dueDate) |\n| `orderBumps` | não | Produtos adicionais exibidos no checkout |\n| `orderBumps.priceId` | sim | priceId do produto adicional |\n| `orderBumps.callToAction` | não | Texto do botão |\n| `orderBumps.title` | não | Título exibido |\n| `orderBumps.description` | não | Descrição exibida |\n| `orderBumps.showImage` | não | Exibir imagem |\n| `primaryColor` | não | Cor primária em hex |\n| `secondaryColor` | não | Cor secundária em hex |\n| `fontColor` | não | Cor do texto em hex |\n| `companyName` | não | Nome da empresa exibido no checkout |\n| `successUrl` | não | Redireciona após pagamento aprovado |\n| `failureUrl` | não | Redireciona após pagamento recusado |\n| `termsOfServiceUrl` | não | Termos de serviço exibidos no checkout para aceite do cliente |\n| `privacyPolicyUrl` | não | Política de privacidade exibida no checkout para aceite do cliente |","body":{"mode":"raw","raw":"{\n  \"priceId\": \"price_abc123\",\n  \"allowedPaymentMethods\": [\n    \"pix\",\n    \"creditcard\",\n    \"boleto\",\n    \"pix_automatico\"\n  ],\n  \"customer\": {\n    \"name\": \"João Silva\",\n    \"email\": \"joao@email.com\",\n    \"documentNumber\": \"12345678901\",\n    \"phone\": \"51999999999\",\n    \"address\": {\n      \"type\": \"BILLING\",\n      \"street\": \"Rua das Flores\",\n      \"number\": \"123\",\n      \"complement\": \"Apto 4\",\n      \"neighborhood\": \"Centro\",\n      \"city\": \"Porto Alegre\",\n      \"state\": \"RS\",\n      \"zipCode\": \"90010000\",\n      \"country\": \"BR\",\n      \"cityCode\": \"4314902\"\n    }\n  },\n  \"items\": [\n    {\n      \"priceId\": \"price_abc123\",\n      \"quantity\": 1\n    }\n  ],\n  \"billingDay\": 15,\n  \"prorataStartDate\": \"2026-06-11\",\n  \"installments\": 1,\n  \"dueDate\": \"2026-07-30\",\n  \"boletoDueDays\": 7,\n  \"expirationAfterDueDate\": 30,\n  \"discounts\": [\n    {\n      \"type\": \"PERCENTAGE\",\n      \"value\": 10,\n      \"paymentMethod\": \"pix\",\n      \"fromCycle\": 1,\n      \"toCycle\": 3,\n      \"durationMonths\": 3\n    }\n  ],\n  \"passFeesToCustomer\": false,\n  \"freeInstallments\": 1,\n  \"maxInstallments\": 12,\n  \"boletoInstructions\": {\n    \"fine\": 2.0,\n    \"interest\": 1.0,\n    \"discount\": {\n      \"amount\": 10.00,\n      \"modality\": \"fixed\",\n      \"limitDate\": \"2026-07-28\"\n    }\n  },\n  \"orderBumps\": [\n    {\n      \"priceId\": \"price_bump123\",\n      \"callToAction\": \"Adicionar ao pedido\",\n      \"title\": \"Produto adicional\",\n      \"description\": \"Descrição do order bump\",\n      \"showImage\": true\n    }\n  ],\n  \"primaryColor\": \"#6366f1\",\n  \"secondaryColor\": \"#818cf8\",\n  \"fontColor\": \"#ffffff\",\n  \"companyName\": \"Minha Empresa\",\n  \"successUrl\": \"https://meusite.com/sucesso\",\n  \"failureUrl\": \"https://meusite.com/falha\",\n  \"termsOfServiceUrl\": \"https://meusite.com/termos-de-servico\",\n  \"privacyPolicyUrl\": \"https://meusite.com/politica-de-privacidade\",\n  \"metadata\": { \"referencia\": \"pedido-001\" }\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"cs_abc123\",\n  \"url\": \"https://app.validapay.com.br/pagamento/cs_abc123\",\n  \"priceId\": \"price_abc123\"\n}","cookie":[]},{"name":"400","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"error\": {\n    \"code\": \"INVALID_DATA\",\n    \"message\": \"Campo inválido\",\n    \"details\": []\n  }\n}","cookie":[]},{"name":"401","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Você não tem permissão para usar este produto\",\n        \"code\": \"FORBIDDEN\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Preço não encontrado\",\n        \"code\": \"PRICE_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Buscar sessão de pagamento","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/checkout-sessions/:id","protocol":"https","host":["api","validapay","com","br"],"path":["v1","checkout-sessions",":id"],"variable":[{"key":"id","value":"cs_xxx","description":"ID da sessão de checkout (ex: cs_xxx) - required"}]},"description":"@scopes checkouts/read\n\n@top\n\nRetorna os dados de uma sessão de checkout ativa, como produtos disponíveis e formas de pagamento."},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"cs_xxx\",\n  \"status\": \"PENDING\",\n  \"priceId\": \"price_xxx\"\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Sessão não encontrada\",\n        \"code\": \"SESSION_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]}]},{"name":"Checkout Transparente","item":[{"name":"Gerar cobrança PIX","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"https://api.validapay.com.br/v1/charges","protocol":"https","host":["api","validapay","com","br"],"path":["v1","charges"]},"description":"@scopes checkouts/write\n\n@top\n\nGera uma cobrança **PIX** pelo checkout transparente. O cliente informa os dados diretamente na sua própria interface e você os envia para a API.\n\nEnvie os dados do comprador e os itens da compra. A resposta traz o código `emv` (copia e cola) e o QR Code para pagamento.\n\nProduto ou valor: envie `items` com os produtos OU `amount` para uma cobrança avulsa.\n\nNotificações por e-mail: use `notifications` para escolher quais e-mails saem nesta cobrança. Eventos aceitos aqui: `oneoff.pix.generated` (envia o QR Code ao comprador assim que a cobrança é criada), `oneoff.payment.success` (confirmação ao comprador quando o Pix compensa) e `new.sale` (avisa você, vendedor, da venda paga). Os eventos destinados ao comprador exigem `customer.email`. Sem o campo, uma cobrança avulsa (enviada com `amount`) não dispara e-mail nenhum; com `items` de um produto, vale a configuração de notificações do produto, e `notifications` no payload tem precedência sobre ela.\n\n> ⚠️ **Atenção:** envie o campo `externalId` como chave de idempotência (idempotencyKey). Se duas cobranças forem enviadas com o mesmo `externalId`, a segunda é recusada com `409 DUPLICATE_CHARGE`, retornando o `chargeId` da cobrança original.\n\nErros comuns: `409 DUPLICATE_CHARGE` (externalId já utilizado), `404 PRICE_NOT_FOUND` (preço inexistente) e `400 INVALID_DATA` (campo inválido).\n\nUse `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.\n\n**Correlação com o pedido:** use `externalId` — ele é persistido e devolvido. O campo `metadata` é aceito nesta rota mas **não é gravado na cobrança** nem volta no webhook; ele só é persistido em `POST /v1/charges/pix`.\n\n### Emitindo nota fiscal na cobrança\n\nEnvie `nfConfigId` com o identificador de uma configuração fiscal criada em `POST /v1/invoices/notas/config`. Com ele presente:\n\n- `customer.address` passa a ser **obrigatório** — a nota precisa do endereço do tomador. Sem ele: `400 INVALID_DATA`.\n- O momento da emissão vem da configuração, não da cobrança: `invoiceTiming` aceita `IMMEDIATE` (padrão), `AFTER_CONFIRMATION` e `DAYS_AFTER_CONFIRMATION`; neste último, `daysAfterConfirmation` define em quantos dias (padrão 1).\n- O `cityCode` (IBGE) do endereço é resolvido a partir do CEP e é necessário para a NFS-e.\n\nO mesmo campo existe em produtos (`POST /v1/products`) e nas configurações de assinatura, para emitir nota a cada ciclo sem repetir o `nfConfigId` em cada cobrança.\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `paymentMethod` | sim | Forma de pagamento (fixo: pix) |\n| `externalId` | não | Identificador único do pedido no seu sistema; usado como idempotencyKey (evita cobrança duplicada) |\n| `externalTxid` | não | Identifica a loja, o caixa ou o vendedor responsável pela cobrança |\n| `customer` | sim | Dados do comprador |\n| `customer.name` | sim | Nome completo |\n| `customer.email` | sim | E-mail |\n| `customer.documentNumber` | sim | CPF (11) ou CNPJ (14 dígitos) |\n| `customer.phone` | não | Telefone |\n| `customer.cep` | não | CEP (necessário para PIX com dados do pagador) |\n| `items` | não | Produtos da compra (ou use amount para cobrança avulsa) |\n| `items.priceId` | sim | ID do preço do produto |\n| `items.quantity` | não | Quantidade (default 1) |\n| `expiration` | não | Expiração do QR Code PIX (YYYY-MM-DD) |\n| `couponCode` | não | Código de cupom de desconto |\n| `description` | não | Descricao livre da cobranca |\n| `split` | não | Divisao do valor. Nao suportado em creditcard nem pix_automatico |\n| `installments` | não | Parcelas no cartao, de 1 a 12 |\n| `freeInstallments` | não | Parcelas sem juros para o comprador, de 0 a 12 |\n| `passFeesToCustomer` | não | Repassa a taxa de parcelamento ao comprador |\n| `nfConfigId` | não | Emite nota fiscal com esta configuracao. Exige customer.address |\n| `discounts` | não | Descontos aplicados a cobranca |\n| `discounts.type` | sim | Tipo do desconto: percentual sobre o valor ou abatimento fixo em reais |\n| `discounts.value` | sim | Percentual de 0 a 100 quando type e percentage; valor em reais quando fixed |\n| `discounts.paymentMethod` | não | Aplica o desconto so neste metodo de pagamento |\n| `discounts.fromCycle` | não | Primeiro ciclo em que o desconto vale, em cobrancas recorrentes |\n| `discounts.toCycle` | não | Ultimo ciclo; null mantem o desconto ate o fim da assinatura |\n| `discounts.durationMonths` | não | Alternativa a toCycle: por quantos meses o desconto vale |\n| `tokenId` | não | Alternativa a card e a paymentMethodId no cartao |\n| `productId` | não | Cria a cobranca a partir de um produto |\n| `recurrencyStartDate` | não | Primeira cobranca da recorrencia (YYYY-MM-DD) |\n| `prorataStartDate` | não | Inicio do calculo pro rata |\n| `prorataDueDate` | não | Vencimento da cobranca pro rata (YYYY-MM-DD) |\n| `mergeWithNextCycle` | não | Junta a pro rata com o proximo ciclo em vez de cobrar agora |","body":{"mode":"raw","raw":"{\n  \"paymentMethod\": \"pix\",\n  \"externalId\": \"pedido-2026-0001\",\n  \"externalTxid\": \"loja-01-caixa-03\",\n  \"customer\": {\n    \"name\": \"João da Silva\",\n    \"email\": \"joao@email.com\",\n    \"documentNumber\": \"12345678901\",\n    \"phone\": \"+5511999998888\",\n    \"cep\": \"01310100\"\n  },\n  \"items\": [\n    {\n      \"priceId\": \"price_abc123\",\n      \"quantity\": 1\n    }\n  ],\n  \"expiration\": \"2026-07-30\",\n  \"couponCode\": \"PROMO10\",\n  \"metadata\": { \"referencia\": \"pedido-001\" },\n  \"description\": \"Assinatura Premium\",\n  \"split\": [\n    { \"type\": \"fixed\", \"accountNumber\": \"896532569\", \"amount\": 0.10 }\n  ],\n  \"installments\": 1,\n  \"freeInstallments\": 1,\n  \"passFeesToCustomer\": false,\n  \"allowedPaymentMethods\": [\"pix\", \"creditcard\"],\n  \"nfConfigId\": \"nfc_1788364755079_psuecwgdc\",\n  \"notifications\": [\"oneoff.pix.generated\", \"oneoff.payment.success\", \"new.sale\"],\n  \"discounts\": [\n    {\n      \"type\": \"percentage\",\n      \"value\": 10,\n      \"paymentMethod\": \"pix\",\n      \"fromCycle\": 1,\n      \"toCycle\": 3,\n      \"durationMonths\": 3\n    }\n  ],\n  \"tokenId\": \"tok_abc123\",\n  \"productId\": \"prod_123456_example\",\n  \"recurrencyStartDate\": \"2026-10-01\",\n  \"prorataStartDate\": \"2026-09-15\",\n  \"prorataDueDate\": \"2026-09-20\",\n  \"mergeWithNextCycle\": false\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"customerId\": \"cus_xxx\",\n  \"chargeId\": \"cha_abc123\",\n  \"pix\": {\n    \"emv\": \"00020126330014br.gov.bcb.pix...5204000053039865802BR6304ABCD\",\n    \"qrCode\": \"data:image/png;base64,iVBORw0KGgo...\"\n  }\n}","cookie":[]},{"name":"404 PRICE_NOT_FOUND","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"error\": {\n    \"message\": \"Preço não encontrado\",\n    \"code\": \"PRICE_NOT_FOUND\"\n  }\n}","cookie":[]},{"name":"409 DUPLICATE_CHARGE","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"Conflict","code":409,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"error\": {\n    \"message\": \"Cobrança duplicada: já existe uma cobrança para este pedido\",\n    \"code\": \"DUPLICATE_CHARGE\",\n    \"details\": {\n      \"chargeId\": \"cha_1784065113577_5dw2oyfic\"\n    },\n    \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n  }\n}","cookie":[]}]},{"name":"Gerar cobrança Pix Automático","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"https://api.validapay.com.br/v1/charges","protocol":"https","host":["api","validapay","com","br"],"path":["v1","charges"]},"description":"@scopes checkouts/write\n\n@top\n\nInicia uma assinatura com **Pix Automático** pelo checkout transparente. O cliente informa os dados na sua própria interface e você os envia para a API.\n\nA resposta traz `pix.emv` (copia e cola) e `pix.recurrencyId`.\n\nEnquanto o banco do pagador não confirma a autorização, a assinatura fica com status `PENDING`.\n\nRequisitos:\n\n- conta ValidaPay cadastrada como **PJ** (CNPJ)\n- `items` com preço **recorrente** (`recurrenceType` WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL ou YEARLY); não use `amount` avulso\n- valor mínimo de **R$ 4,99** por cobrança\n\nNotificações por e-mail: use `notifications` para escolher quais e-mails saem nesta cobrança. Eventos aceitos aqui: `oneoff.payment.success` (confirmação ao comprador quando o Pix compensa) e `new.sale` (avisa você, vendedor, da venda paga). Os eventos destinados ao comprador exigem `customer.email`. Sem o campo, uma cobrança avulsa (enviada com `amount`) não dispara e-mail nenhum; com `items` de um produto, vale a configuração de notificações do produto, e `notifications` no payload tem precedência sobre ela.\n\n> ⚠️ **Atenção:** envie o campo `externalId` como chave de idempotência (idempotencyKey). Se duas cobranças forem enviadas com o mesmo `externalId`, a segunda é recusada com `409 DUPLICATE_CHARGE`, retornando o `chargeId` da cobrança original.\n\nErros comuns: `400 PIX_AUTOMATICO_PJ_ONLY` (conta PF), `400 PIX_AUTOMATICO_MIN_AMOUNT` (valor abaixo do mínimo), `409 DUPLICATE_CHARGE` (externalId já utilizado) e `404 PRICE_NOT_FOUND` (preço inexistente).\n\nUse `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.\n\n**Correlação com o pedido:** use `externalId` — ele é persistido e devolvido. O campo `metadata` é aceito nesta rota mas **não é gravado na cobrança** nem volta no webhook; ele só é persistido em `POST /v1/charges/pix`.\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `paymentMethod` | sim | Forma de pagamento (fixo: pix_automatico) |\n| `externalId` | não | Identificador único do pedido no seu sistema; usado como idempotencyKey (evita cobrança duplicada) |\n| `externalTxid` | não | Identifica a loja, o caixa ou o vendedor responsável pela cobrança |\n| `customer` | sim | Dados do comprador |\n| `customer.name` | sim | Nome completo |\n| `customer.email` | sim | E-mail |\n| `customer.documentNumber` | sim | CPF (11) ou CNPJ (14 dígitos) |\n| `customer.phone` | não | Telefone |\n| `items` | sim | Itens da assinatura; o preço precisa ser recorrente |\n| `items.priceId` | sim | ID do preço recorrente (valor mínimo de R$ 4,99) |\n| `items.quantity` | não | Quantidade (default 1) |\n| `billingDay` | não | Dia do mês das cobranças seguintes (1 a 31) |\n| `couponCode` | não | Código de cupom de desconto |\n| `description` | não | Descricao livre da cobranca |\n| `split` | não | Divisao do valor. Nao suportado em creditcard nem pix_automatico |\n| `installments` | não | Parcelas no cartao, de 1 a 12 |\n| `freeInstallments` | não | Parcelas sem juros para o comprador, de 0 a 12 |\n| `passFeesToCustomer` | não | Repassa a taxa de parcelamento ao comprador |\n| `nfConfigId` | não | Emite nota fiscal com esta configuracao. Exige customer.address |\n| `discounts` | não | Descontos aplicados a cobranca |\n| `discounts.type` | sim | Tipo do desconto: percentual sobre o valor ou abatimento fixo em reais |\n| `discounts.value` | sim | Percentual de 0 a 100 quando type e percentage; valor em reais quando fixed |\n| `discounts.paymentMethod` | não | Aplica o desconto so neste metodo de pagamento |\n| `discounts.fromCycle` | não | Primeiro ciclo em que o desconto vale, em cobrancas recorrentes |\n| `discounts.toCycle` | não | Ultimo ciclo; null mantem o desconto ate o fim da assinatura |\n| `discounts.durationMonths` | não | Alternativa a toCycle: por quantos meses o desconto vale |\n| `tokenId` | não | Alternativa a card e a paymentMethodId no cartao |\n| `productId` | não | Cria a cobranca a partir de um produto |\n| `recurrencyStartDate` | não | Primeira cobranca da recorrencia (YYYY-MM-DD) |\n| `prorataStartDate` | não | Inicio do calculo pro rata |\n| `prorataDueDate` | não | Vencimento da cobranca pro rata (YYYY-MM-DD) |\n| `mergeWithNextCycle` | não | Junta a pro rata com o proximo ciclo em vez de cobrar agora |","body":{"mode":"raw","raw":"{\n  \"paymentMethod\": \"pix_automatico\",\n  \"externalId\": \"assinatura-2026-0001\",\n  \"externalTxid\": \"loja-01-caixa-03\",\n  \"customer\": {\n    \"name\": \"João da Silva\",\n    \"email\": \"joao@email.com\",\n    \"documentNumber\": \"12345678901\",\n    \"phone\": \"+5511999998888\"\n  },\n  \"items\": [\n    {\n      \"priceId\": \"price_abc123\",\n      \"quantity\": 1\n    }\n  ],\n  \"billingDay\": 15,\n  \"couponCode\": \"PROMO10\",\n  \"metadata\": { \"referencia\": \"assinatura-001\" },\n  \"description\": \"Assinatura Premium\",\n  \"split\": [\n    { \"type\": \"fixed\", \"accountNumber\": \"896532569\", \"amount\": 0.10 }\n  ],\n  \"installments\": 1,\n  \"freeInstallments\": 1,\n  \"passFeesToCustomer\": false,\n  \"allowedPaymentMethods\": [\"pix\", \"creditcard\"],\n  \"nfConfigId\": \"nfc_1788364755079_psuecwgdc\",\n  \"notifications\": [\"oneoff.pix.generated\", \"new.sale\"],\n  \"discounts\": [\n    {\n      \"type\": \"percentage\",\n      \"value\": 10,\n      \"paymentMethod\": \"pix\",\n      \"fromCycle\": 1,\n      \"toCycle\": 3,\n      \"durationMonths\": 3\n    }\n  ],\n  \"tokenId\": \"tok_abc123\",\n  \"productId\": \"prod_123456_example\",\n  \"recurrencyStartDate\": \"2026-10-01\",\n  \"prorataStartDate\": \"2026-09-15\",\n  \"prorataDueDate\": \"2026-09-20\",\n  \"mergeWithNextCycle\": false\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"customerId\": \"cus_xxx\",\n  \"chargeId\": \"cha_abc123\",\n  \"pix\": {\n    \"emv\": \"00020126330014br.gov.bcb.pix...5204000053039865802BR6304ABCD\",\n    \"recurrencyId\": \"RN1234567890abcdef\"\n  }\n}","cookie":[]},{"name":"400 PIX_AUTOMATICO_PJ_ONLY","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"error\": {\n    \"message\": \"Pix Automático está disponível apenas para contas PJ\",\n    \"code\": \"PIX_AUTOMATICO_PJ_ONLY\"\n  }\n}","cookie":[]},{"name":"400 PIX_AUTOMATICO_MIN_AMOUNT","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"error\": {\n    \"message\": \"Pix Automático exige valor mínimo de R$ 4,99\",\n    \"code\": \"PIX_AUTOMATICO_MIN_AMOUNT\"\n  }\n}","cookie":[]}]},{"name":"Gerar cobrança Boleto","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"https://api.validapay.com.br/v1/charges","protocol":"https","host":["api","validapay","com","br"],"path":["v1","charges"]},"description":"@scopes checkouts/write\n\n@top\n\nGera uma cobrança via **boleto** pelo checkout transparente. O cliente informa os dados na sua própria interface e você os envia para a API.\n\nPara boleto, o **endereço completo do comprador é obrigatório**. Você pode personalizar vencimento, multa, juros e desconto por meio de `boletoInstructions`.\n\nProduto ou valor: envie `items` com os produtos OU `amount` para uma cobrança avulsa.\n\nNotificações por e-mail: use `notifications` para escolher quais e-mails saem nesta cobrança. Eventos aceitos aqui: `oneoff.boleto.generated` (envia o boleto ao comprador assim que a cobrança é criada), `oneoff.payment.success` (confirmação ao comprador quando o boleto compensa) e `new.sale` (avisa você, vendedor, da venda paga). Os eventos destinados ao comprador exigem `customer.email`. Sem o campo, uma cobrança avulsa (enviada com `amount`) não dispara e-mail nenhum; com `items` de um produto, vale a configuração de notificações do produto, e `notifications` no payload tem precedência sobre ela.\n\n> ⚠️ **Atenção:** envie o campo `externalId` como chave de idempotência (idempotencyKey). Se duas cobranças forem enviadas com o mesmo `externalId`, a segunda é recusada com `409 DUPLICATE_CHARGE`, retornando o `chargeId` da cobrança original.\n\nErros comuns: `409 DUPLICATE_CHARGE` (externalId já utilizado), `404 PRICE_NOT_FOUND` (preço inexistente) e `400 INVALID_DATA` (campo inválido — inclui endereço ausente).\n\nUse `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.\n\n**Correlação com o pedido:** use `externalId` — ele é persistido e devolvido. O campo `metadata` é aceito nesta rota mas **não é gravado na cobrança** nem volta no webhook; ele só é persistido em `POST /v1/charges/pix`.\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `paymentMethod` | sim | Forma de pagamento (fixo: boleto) |\n| `externalId` | não | Identificador único do pedido no seu sistema; usado como idempotencyKey (evita cobrança duplicada) |\n| `externalTxid` | não | Identifica a loja, o caixa ou o vendedor responsável pela cobrança |\n| `customer` | sim | Dados do comprador |\n| `customer.name` | sim | Nome completo |\n| `customer.email` | sim | E-mail |\n| `customer.documentNumber` | sim | CPF (11) ou CNPJ (14 dígitos) |\n| `customer.phone` | não | Telefone |\n| `customer.address` | sim | Endereço do comprador (obrigatório para boleto) |\n| `customer.address.street` | sim | Rua ou logradouro |\n| `customer.address.number` | sim | Número |\n| `customer.address.complement` | não | Complemento |\n| `customer.address.neighborhood` | sim | Bairro |\n| `customer.address.city` | sim | Cidade |\n| `customer.address.state` | sim | UF com 2 letras |\n| `customer.address.zipCode` | sim | CEP com 8 dígitos |\n| `customer.address.country` | não | País (default BR) |\n| `customer.address.cityCode` | não | Código IBGE (necessário para nota fiscal) |\n| `items` | não | Produtos da compra (ou use amount para cobrança avulsa) |\n| `items.priceId` | sim | ID do preço do produto |\n| `items.quantity` | não | Quantidade (default 1) |\n| `dueDate` | não | Vencimento do boleto (YYYY-MM-DD, maior que hoje) |\n| `boletoDueDays` | não | Dias até o vencimento (mín. 1; ignorado se dueDate informado) |\n| `expirationAfterDueDate` | não | Dias para cancelar o boleto após o vencimento (0 a 60) |\n| `boletoInstructions` | não | Regras de multa/juros/desconto do boleto |\n| `boletoInstructions.fine` | não | Multa por atraso em % (0.1 a 100; fine + interest <= 60) |\n| `boletoInstructions.interest` | não | Juros mensais por atraso em % (0.1 a 100) |\n| `boletoInstructions.discount` | não | Desconto para pagamento antecipado |\n| `boletoInstructions.discount.amount` | não | Valor do desconto |\n| `boletoInstructions.discount.modality` | não | fixed (R$) ou percent (%) |\n| `boletoInstructions.discount.limitDate` | não | Data limite do desconto (antes de dueDate) |\n| `couponCode` | não | Código de cupom de desconto |\n| `description` | não | Descricao livre da cobranca |\n| `split` | não | Divisao do valor. Nao suportado em creditcard nem pix_automatico |\n| `installments` | não | Parcelas no cartao, de 1 a 12 |\n| `freeInstallments` | não | Parcelas sem juros para o comprador, de 0 a 12 |\n| `passFeesToCustomer` | não | Repassa a taxa de parcelamento ao comprador |\n| `nfConfigId` | não | Emite nota fiscal com esta configuracao. Exige customer.address |\n| `discounts` | não | Descontos aplicados a cobranca |\n| `discounts.type` | sim | Tipo do desconto: percentual sobre o valor ou abatimento fixo em reais |\n| `discounts.value` | sim | Percentual de 0 a 100 quando type e percentage; valor em reais quando fixed |\n| `discounts.paymentMethod` | não | Aplica o desconto so neste metodo de pagamento |\n| `discounts.fromCycle` | não | Primeiro ciclo em que o desconto vale, em cobrancas recorrentes |\n| `discounts.toCycle` | não | Ultimo ciclo; null mantem o desconto ate o fim da assinatura |\n| `discounts.durationMonths` | não | Alternativa a toCycle: por quantos meses o desconto vale |\n| `tokenId` | não | Alternativa a card e a paymentMethodId no cartao |\n| `productId` | não | Cria a cobranca a partir de um produto |\n| `recurrencyStartDate` | não | Primeira cobranca da recorrencia (YYYY-MM-DD) |\n| `prorataStartDate` | não | Inicio do calculo pro rata |\n| `prorataDueDate` | não | Vencimento da cobranca pro rata (YYYY-MM-DD) |\n| `mergeWithNextCycle` | não | Junta a pro rata com o proximo ciclo em vez de cobrar agora |","body":{"mode":"raw","raw":"{\n  \"paymentMethod\": \"boleto\",\n  \"externalId\": \"pedido-2026-0001\",\n  \"externalTxid\": \"loja-01-caixa-03\",\n  \"customer\": {\n    \"name\": \"João da Silva\",\n    \"email\": \"joao@email.com\",\n    \"documentNumber\": \"12345678901\",\n    \"phone\": \"+5511999998888\",\n    \"address\": {\n      \"street\": \"Av. Paulista\",\n      \"number\": \"1000\",\n      \"complement\": \"Apto 52\",\n      \"neighborhood\": \"Bela Vista\",\n      \"city\": \"São Paulo\",\n      \"state\": \"SP\",\n      \"zipCode\": \"01310100\",\n      \"country\": \"BR\",\n      \"cityCode\": \"3550308\"\n    }\n  },\n  \"items\": [\n    {\n      \"priceId\": \"price_abc123\",\n      \"quantity\": 1\n    }\n  ],\n  \"dueDate\": \"2026-07-30\",\n  \"boletoDueDays\": 7,\n  \"expirationAfterDueDate\": 30,\n  \"boletoInstructions\": {\n    \"fine\": 2.0,\n    \"interest\": 1.0,\n    \"discount\": {\n      \"amount\": 10.0,\n      \"modality\": \"fixed\",\n      \"limitDate\": \"2026-07-28\"\n    }\n  },\n  \"couponCode\": \"PROMO10\",\n  \"metadata\": { \"referencia\": \"pedido-001\" },\n  \"description\": \"Assinatura Premium\",\n  \"split\": [\n    { \"type\": \"fixed\", \"accountNumber\": \"896532569\", \"amount\": 0.10 }\n  ],\n  \"installments\": 1,\n  \"freeInstallments\": 1,\n  \"passFeesToCustomer\": false,\n  \"allowedPaymentMethods\": [\"pix\", \"creditcard\"],\n  \"nfConfigId\": \"nfc_1788364755079_psuecwgdc\",\n  \"notifications\": [\"oneoff.pix.generated\", \"oneoff.payment.success\", \"new.sale\"],\n  \"discounts\": [\n    {\n      \"type\": \"percentage\",\n      \"value\": 10,\n      \"paymentMethod\": \"pix\",\n      \"fromCycle\": 1,\n      \"toCycle\": 3,\n      \"durationMonths\": 3\n    }\n  ],\n  \"tokenId\": \"tok_abc123\",\n  \"productId\": \"prod_123456_example\",\n  \"recurrencyStartDate\": \"2026-10-01\",\n  \"prorataStartDate\": \"2026-09-15\",\n  \"prorataDueDate\": \"2026-09-20\",\n  \"mergeWithNextCycle\": false\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"customerId\": \"cus_xxx\",\n  \"chargeId\": \"cha_abc123\",\n  \"boleto\": {\n    \"digitableLine\": \"23793.38128 60007.827136 95000.063305 9 84410000010000\",\n    \"barCode\": \"23799844100000100003381260007827139500006330\",\n    \"dueDate\": \"2026-07-30\",\n    \"pdfUrl\": \"https://app.validapay.com.br/boletos/cha_abc123.pdf\"\n  }\n}","cookie":[]},{"name":"404 PRICE_NOT_FOUND","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"error\": {\n    \"message\": \"Preço não encontrado\",\n    \"code\": \"PRICE_NOT_FOUND\"\n  }\n}","cookie":[]},{"name":"409 DUPLICATE_CHARGE","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"Conflict","code":409,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"error\": {\n    \"message\": \"Cobrança duplicada: já existe uma cobrança para este pedido\",\n    \"code\": \"DUPLICATE_CHARGE\",\n    \"details\": {\n      \"chargeId\": \"cha_1784065113577_5dw2oyfic\"\n    },\n    \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n  }\n}","cookie":[]}]},{"name":"Gerar cobrança Cartão","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"url":{"raw":"https://api.validapay.com.br/v1/charges","protocol":"https","host":["api","validapay","com","br"],"path":["v1","charges"]},"description":"@scopes checkouts/write\n\n@top\n\nGera uma cobrança via **cartão de crédito** pelo checkout transparente. O cliente informa os dados na sua própria interface e você os envia para a API.\n\nEnvie os dados do cartão no objeto `card` (dados brutos) ou use `paymentMethodId`/`tokenId` de um cartão tokenizado. É possível parcelar (`installments`) e repassar as taxas ao comprador.\n\nProduto ou valor: envie `items` com os produtos OU `amount` para uma cobrança avulsa.\n\nNotificações por e-mail: use `notifications` para escolher quais e-mails saem nesta cobrança. Eventos aceitos aqui: `oneoff.payment.success` (confirmação ao comprador quando o cartão é aprovado), `oneoff.payment.failed` (aviso ao comprador quando o cartão é recusado) e `new.sale` (avisa você, vendedor, da venda paga). Os eventos destinados ao comprador exigem `customer.email`. Sem o campo, uma cobrança avulsa (enviada com `amount`) não dispara e-mail nenhum; com `items` de um produto, vale a configuração de notificações do produto, e `notifications` no payload tem precedência sobre ela.\n\n> ⚠️ **Atenção:** envie o campo `externalId` como chave de idempotência (idempotencyKey). Se duas cobranças forem enviadas com o mesmo `externalId`, a segunda é recusada com `409 DUPLICATE_CHARGE`, retornando o `chargeId` da cobrança original.\n\nErros comuns: `409 DUPLICATE_CHARGE` (externalId já utilizado), `402` (pagamento recusado pelo banco), `400 MISSING_CARD_DATA` (faltam dados do cartão) e `404 PRICE_NOT_FOUND` (preço inexistente).\n\n**Cartões de teste (sandbox):** em conta de sandbox nenhuma cobrança chega ao adquirente — o número do cartão é que define o resultado:\n\n- `4111111111111111` — pagamento aprovado\n- `4000000000000002` — recusado pela operadora (`card_declined`)\n- `4000000000000004` — saldo insuficiente (`insufficient_funds`)\n- `4000000000000006` — cartão expirado (`expired_card`)\n- `4000000000000008` — CVV inválido (`invalid_cvv`)\n- `4000000000000010` — suspeita de fraude (`fraud_suspected`)\n\nQualquer outro número de 16 dígitos é aprovado. CVV, validade e nome do titular podem ser quaisquer valores válidos. Em produção o número não muda nada: quem decide é o emissor do cartão.\n\nUse `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.\n\n**Correlação com o pedido:** use `externalId` — ele é persistido e devolvido. O campo `metadata` é aceito nesta rota mas **não é gravado na cobrança** nem volta no webhook; ele só é persistido em `POST /v1/charges/pix`.\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `paymentMethod` | sim | Forma de pagamento (fixo: creditcard) |\n| `externalId` | não | Identificador único do pedido no seu sistema; usado como idempotencyKey (evita cobrança duplicada) |\n| `externalTxid` | não | Identifica a loja, o caixa ou o vendedor responsável pela cobrança |\n| `customer` | sim | Dados do comprador |\n| `customer.name` | sim | Nome completo |\n| `customer.email` | sim | E-mail |\n| `customer.documentNumber` | sim | CPF (11) ou CNPJ (14 dígitos) |\n| `customer.phone` | não | Telefone |\n| `card` | sim | Dados do cartão (ou use paymentMethodId/tokenId de um cartão salvo) |\n| `card.number` | sim | Número do cartão (13 a 19 dígitos) |\n| `card.cvv` | sim | Código de segurança (3 ou 4 dígitos) |\n| `card.name` | sim | Nome como está no cartão |\n| `card.expiration` | sim | Validade no formato MM/YYYY |\n| `paymentMethodId` | não | Cartão tokenizado (alternativa ao objeto card) |\n| `items` | não | Produtos da compra (ou use amount para cobrança avulsa) |\n| `items.priceId` | sim | ID do preço do produto |\n| `items.quantity` | não | Quantidade (default 1) |\n| `installments` | não | Parcelas no cartao, de 1 a 12 |\n| `passFeesToCustomer` | não | Repassa a taxa de parcelamento ao comprador |\n| `freeInstallments` | não | Parcelas sem juros para o comprador, de 0 a 12 |\n| `couponCode` | não | Código de cupom de desconto |\n| `description` | não | Descricao livre da cobranca |\n| `split` | não | Divisao do valor. Nao suportado em creditcard nem pix_automatico |\n| `nfConfigId` | não | Emite nota fiscal com esta configuracao. Exige customer.address |\n| `discounts` | não | Descontos aplicados a cobranca |\n| `discounts.type` | sim | Tipo do desconto: percentual sobre o valor ou abatimento fixo em reais |\n| `discounts.value` | sim | Percentual de 0 a 100 quando type e percentage; valor em reais quando fixed |\n| `discounts.paymentMethod` | não | Aplica o desconto so neste metodo de pagamento |\n| `discounts.fromCycle` | não | Primeiro ciclo em que o desconto vale, em cobrancas recorrentes |\n| `discounts.toCycle` | não | Ultimo ciclo; null mantem o desconto ate o fim da assinatura |\n| `discounts.durationMonths` | não | Alternativa a toCycle: por quantos meses o desconto vale |\n| `tokenId` | não | Alternativa a card e a paymentMethodId no cartao |\n| `productId` | não | Cria a cobranca a partir de um produto |\n| `recurrencyStartDate` | não | Primeira cobranca da recorrencia (YYYY-MM-DD) |\n| `prorataStartDate` | não | Inicio do calculo pro rata |\n| `prorataDueDate` | não | Vencimento da cobranca pro rata (YYYY-MM-DD) |\n| `mergeWithNextCycle` | não | Junta a pro rata com o proximo ciclo em vez de cobrar agora |","body":{"mode":"raw","raw":"{\n  \"paymentMethod\": \"creditcard\",\n  \"externalId\": \"pedido-2026-0001\",\n  \"externalTxid\": \"loja-01-caixa-03\",\n  \"customer\": {\n    \"name\": \"João da Silva\",\n    \"email\": \"joao@email.com\",\n    \"documentNumber\": \"12345678901\",\n    \"phone\": \"+5511999998888\"\n  },\n  \"card\": {\n    \"number\": \"4111111111111111\",\n    \"cvv\": \"123\",\n    \"name\": \"JOAO DA SILVA\",\n    \"expiration\": \"12/2027\"\n  },\n  \"paymentMethodId\": \"pm_abc123\",\n  \"items\": [\n    {\n      \"priceId\": \"price_abc123\",\n      \"quantity\": 1\n    }\n  ],\n  \"installments\": 1,\n  \"passFeesToCustomer\": false,\n  \"freeInstallments\": 1,\n  \"couponCode\": \"PROMO10\",\n  \"metadata\": { \"referencia\": \"pedido-001\" },\n  \"description\": \"Assinatura Premium\",\n  \"split\": [\n    { \"type\": \"fixed\", \"accountNumber\": \"896532569\", \"amount\": 0.10 }\n  ],\n  \"installments\": 1,\n  \"freeInstallments\": 1,\n  \"passFeesToCustomer\": false,\n  \"allowedPaymentMethods\": [\"pix\", \"creditcard\"],\n  \"nfConfigId\": \"nfc_1788364755079_psuecwgdc\",\n  \"notifications\": [\"oneoff.pix.generated\", \"oneoff.payment.success\", \"new.sale\"],\n  \"discounts\": [\n    {\n      \"type\": \"percentage\",\n      \"value\": 10,\n      \"paymentMethod\": \"pix\",\n      \"fromCycle\": 1,\n      \"toCycle\": 3,\n      \"durationMonths\": 3\n    }\n  ],\n  \"tokenId\": \"tok_abc123\",\n  \"productId\": \"prod_123456_example\",\n  \"recurrencyStartDate\": \"2026-10-01\",\n  \"prorataStartDate\": \"2026-09-15\",\n  \"prorataDueDate\": \"2026-09-20\",\n  \"mergeWithNextCycle\": false\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"customerId\": \"cus_xxx\",\n  \"chargeId\": \"cha_abc123\",\n  \"status\": \"paid\"\n}","cookie":[]},{"name":"402","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"Payment Required","code":402,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"success\": false,\n    \"chargeId\": \"cha_1784065113577_5dw2oyfic\",\n    \"status\": \"failed\",\n    \"error\": \"Cartão recusado\"\n}","cookie":[]},{"name":"400 MISSING_CARD_DATA","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"error\": {\n    \"message\": \"tokenId, card ou paymentMethodId é obrigatório\",\n    \"code\": \"MISSING_CARD_DATA\"\n  }\n}","cookie":[]},{"name":"404 PRICE_NOT_FOUND","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"error\": {\n    \"message\": \"Preço não encontrado\",\n    \"code\": \"PRICE_NOT_FOUND\"\n  }\n}","cookie":[]},{"name":"409 DUPLICATE_CHARGE","originalRequest":{"method":"POST","header":[],"url":{"raw":""}},"status":"Conflict","code":409,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"error\": {\n    \"message\": \"Cobrança duplicada: já existe uma cobrança para este pedido\",\n    \"code\": \"DUPLICATE_CHARGE\",\n    \"details\": {\n      \"chargeId\": \"cha_1784065113577_5dw2oyfic\"\n    },\n    \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n  }\n}","cookie":[]}]}]},{"name":"Simular pagamentos","item":[{"name":"Pagar em sandbox","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/pay/:chargeId//Identificador retornado no ato da geraçao da cobrança","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","pay",":chargeId","","Identificador retornado no ato da geraçao da cobrança"],"variable":[{"key":"chargeId","value":""}]},"description":"@scopes wallet/write\n\n@top\n\nConfirma o pagamento de uma cobrança do **sandbox** sem dinheiro de verdade. A ValidaPay envia ao seu webhook o mesmo evento de PIX recebido que um pagamento real dispararia, então o seu fluxo de baixa é exercitado ponta a ponta.\n\n**Case de uso:**\n\n_Como desenvolvedor integrando a API, quero marcar uma cobrança do sandbox como paga, para testar meu webhook de confirmação sem transferir dinheiro._\n\nInforme no path o `chargeId` devolvido na criação da cobrança. A resposta é imediata e traz `status: PROCESSING` — a confirmação chega pelo webhook; consulte a cobrança depois para vê-la como `PAID`.\n\nDisponível **apenas em contas de sandbox**: em produção a chamada é recusada com `400 NOT_SANDBOX_ACCOUNT`. Cobrança já paga responde `200` com a mensagem \"Cobranca ja foi paga\" e cobrança inexistente, `404 CHARGE_NOT_FOUND`.\n\n**Cartão de crédito não passa por esta rota.** No sandbox o resultado da cobrança no cartão é decidido pelo número enviado:\n\n**Cartões de teste (sandbox):** em conta de sandbox nenhuma cobrança chega ao adquirente — o número do cartão é que define o resultado:\n\n- `4111111111111111` — pagamento aprovado\n- `4000000000000002` — recusado pela operadora (`card_declined`)\n- `4000000000000004` — saldo insuficiente (`insufficient_funds`)\n- `4000000000000006` — cartão expirado (`expired_card`)\n- `4000000000000008` — CVV inválido (`invalid_cvv`)\n- `4000000000000010` — suspeita de fraude (`fraud_suspected`)\n\nQualquer outro número de 16 dígitos é aprovado. CVV, validade e nome do titular podem ser quaisquer valores válidos. Em produção o número não muda nada: quem decide é o emissor do cartão."},"response":[]}]},{"name":"Saques","item":[{"name":"Saque subconta","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n  \"amount\": 1.00,\n  \"pixKey\": \"12345678925\",\n  \"pixKeyType\": \"CPF\",\n  \"accountId\": \"258965356\" \n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/wallet/withdraw","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","withdraw"]},"description":"@scopes wallet/write\n\n@top\n\nCom esta funcionalidade você pode criar um saque em uma subconta associada à sua _master account._\n\n> ⚠️ **Atenção:** Só é possível fazer saques para contas de mesma titularidade\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `amount` | sim | Valor do saque |\n| `pixKey` | sim | Chave Pix de destino |\n| `pixKeyType` | sim | tipo de chave Pix |\n| `accountId` | sim | Número da subconta de destino |"},"response":[{"name":"Sucesso","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n  \"amount\": 1.00,\n  \"pixKey\": \"11111111-2222-3333-4444-555555555555\",\n  \"pixKeyType\": \"EVP\",\n  \"accountNumber\": \"428965347\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/wallet/withdraw","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","withdraw"]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Sat, 07 Mar 2026 11:32:44 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"107"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"3041b69a-6d89-4ad3-bc71-be3a453db475"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"Z2bxkE8MIAMERYA="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-69ac0cd6-5dc889ce025ec8c970e14ba7;Parent=0b3ea1e54233e92e;Sampled=0;Lineage=1:133a49a5:0"}],"cookie":[],"body":"{\n    \"withdrawalId\": \"wdr_1772883158760_tdhomd8xe\",\n    \"status\": \"PROCESSING\",\n    \"amount\": 1,\n    \"accountNumber\": \"258965356\"\n}"},{"name":"Acesso negado","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n  \"amount\": 1.00,\n  \"pixKey\": \"99977766000198\",//\"11111111-2222-3333-4444-555555555555\",\n  \"pixKeyType\": \"CNPJ\",\n  \"accountNumber\": \"438715013\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/wallet/withdraw","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","withdraw"]}},"status":"Unauthorized","code":401,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Tue, 17 Mar 2026 04:01:14 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"140"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"31783dcb-daaa-4106-8f48-c4d797f28d8b"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"aWXBMGgvIAMEdlg="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-69b8d207-36089196431a9e5a6ad18f66;Parent=3e584881c935c09b;Sampled=0;Lineage=1:133a49a5:0"}],"cookie":[],"body":"{\n    \"error\": {\n        \"message\": \"Subconta nao pertence a esta conta\",\n        \"code\": \"OWNERSHIP_MISMATCH\",\n        \"details\": null,\n        \"timestamp\": \"2026-03-17T04:01:14.653Z\"\n    }\n}"},{"name":"Bloqueio por titularidade","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n  \"amount\": 1.00,\n  \"pixKey\": \"99977766000198\",//\"11111111-2222-3333-4444-555555555555\",\n  \"pixKeyType\": \"CNPJ\",\n  \"accountNumber\": \"459013777\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/wallet/withdraw","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","withdraw"]}},"status":"Bad Request","code":400,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Tue, 17 Mar 2026 04:01:57 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"150"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"fa0a30f5-0f79-40c7-8d54-39ca0293251e"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"aWXH3EmnIAMErcA="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-69b8d231-4e5f69a151e352997715380b;Parent=1a5ece3580e3cf20;Sampled=0;Lineage=1:133a49a5:0"}],"cookie":[],"body":"{\n    \"error\": {\n        \"message\": \"A chave PIX nao pertence ao titular da conta\",\n        \"code\": \"OWNERSHIP_MISMATCH\",\n        \"details\": null,\n        \"timestamp\": \"2026-03-17T04:01:57.811Z\"\n    }\n}"}]},{"name":"Saque master account","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n  \"amount\": 1.00,\n  \"pixKey\": \"12345678925\",\n  \"pixKeyType\": \"CPF\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/wallet/withdraw","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","withdraw"]},"description":"@scopes wallet/write\n\n@top\n\nCom esta funcionalidade você pode criar um saque da sua _conta ValidaPay._\n\n> ⚠️ **Atenção:** Só é possível fazer saques para contas de mesma titularidade\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `amount` | sim | Valor do saque |\n| `pixKey` | sim | Chave Pix de destino |\n| `pixKeyType` | sim | tipo de chave Pix |"},"response":[{"name":"Sucesso","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n  \"amount\": 1.00,\n  \"pixKey\": \"11111111-2222-3333-4444-555555555555\",\n  \"pixKeyType\": \"EVP\",\n  \"accountNumber\": \"428965347\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/wallet/withdraw","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","withdraw"]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Sat, 07 Mar 2026 11:32:44 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"107"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"3041b69a-6d89-4ad3-bc71-be3a453db475"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"Z2bxkE8MIAMERYA="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-69ac0cd6-5dc889ce025ec8c970e14ba7;Parent=0b3ea1e54233e92e;Sampled=0;Lineage=1:133a49a5:0"}],"cookie":[],"body":"{\n    \"withdrawalId\": \"wdr_1772883158760_tdhomd8xe\",\n    \"status\": \"PROCESSING\",\n    \"amount\": 1,\n    \"accountNumber\": \"258965356\"\n}"},{"name":"Bloqueio por titularidade","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n  \"amount\": 1.00,\n  \"pixKey\": \"99977766000198\",//\"11111111-2222-3333-4444-555555555555\",\n  \"pixKeyType\": \"CNPJ\",\n  \"accountNumber\": \"459013777\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/wallet/withdraw","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","withdraw"]}},"status":"Bad Request","code":400,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Tue, 17 Mar 2026 04:01:57 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"150"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"fa0a30f5-0f79-40c7-8d54-39ca0293251e"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"aWXH3EmnIAMErcA="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-69b8d231-4e5f69a151e352997715380b;Parent=1a5ece3580e3cf20;Sampled=0;Lineage=1:133a49a5:0"}],"cookie":[],"body":"{\n    \"error\": {\n        \"message\": \"A chave PIX nao pertence ao titular da conta\",\n        \"code\": \"OWNERSHIP_MISMATCH\",\n        \"details\": null,\n        \"timestamp\": \"2026-03-17T04:01:57.811Z\"\n    }\n}"}]}]},{"name":"Extratos","item":[{"name":"Extrato subconta","request":{"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/transactions?accountId=460851686&type=CREDIT&category=PAYMENT&dateFrom=2026-03-01T00:00:00Z&dateTo=2026-03-16T23:00:00Z&limit=5&nextPageToken=eyJTSyI6IjIwMjYtMDMtMTRUMjM6MjM6MzYuMDk2WiN0eG5fMTc3MzUzMDYxNjA5Nl8zOXdmbTk5aTQiLCJhY2NvdW50SWQiOiI0MjkxMzEyMTIifQ","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","transactions"],"query":[{"key":"accountId","value":"460851686","description":"required - ID da subconta a consultar"},{"key":"type","value":"CREDIT","description":"optional - CREDIT ou DEBIT"},{"key":"category","value":"PAYMENT","description":"optional - PAYMENT, PIX_IN, WITHDRAWAL, etc."},{"key":"dateFrom","value":"2026-03-01T00:00:00Z","description":"optional - Data início (ISO 8601)"},{"key":"dateTo","value":"2026-03-16T23:00:00Z","description":"optional - Data fim (ISO 8601)"},{"key":"limit","value":"5","description":"optional - 1-100, default 50"},{"key":"nextPageToken","value":"eyJTSyI6IjIwMjYtMDMtMTRUMjM6MjM6MzYuMDk2WiN0eG5fMTc3MzUzMDYxNjA5Nl8zOXdmbTk5aTQiLCJhY2NvdW50SWQiOiI0MjkxMzEyMTIifQ","description":"optional - Token de paginação"}]},"description":"@scopes wallet/read\n\n@top\n\nCom esta funcionalidade você pode isualizar movimentações em uma subconta associada a sua _master account_"},"response":[{"name":"Sucesso","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{VALIDAPAY_PRD_URL}}/v1/wallet/transactions?type=CREDIT&dateFrom=2026-03-01T00:00:00Z&dateTo=2026-03-16T23:00:00Z&limit=5","host":["{{VALIDAPAY_PRD_URL}}"],"path":["v1","wallet","transactions"],"query":[{"key":"accountId","value":"460851686","description":"required - ID da subconta a consultar","disabled":true},{"key":"type","value":"CREDIT","description":"optional - CREDIT ou DEBIT"},{"key":"category","value":"PAYMENT","description":"optional - PAYMENT, PIX_IN, WITHDRAWAL, etc.","disabled":true},{"key":"dateFrom","value":"2026-03-01T00:00:00Z","description":"optional - Data início (ISO 8601)"},{"key":"dateTo","value":"2026-03-16T23:00:00Z","description":"optional - Data fim (ISO 8601)"},{"key":"limit","value":"5","description":"optional - 1-100, default 50"},{"key":"nextPageToken","value":"eyJTSyI6IjIwMjYtMDMtMTRUMjM6MjM6MzYuMDk2WiN0eG5fMTc3MzUzMDYxNjA5Nl8zOXdmbTk5aTQiLCJhY2NvdW50SWQiOiI0MjkxMzEyMTIifQ","description":"optional - Token de paginação","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Tue, 17 Mar 2026 05:42:20 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"2244"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"d121c426-a1b5-49cf-9dd5-3926475f45aa"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"aWl1gHMyoAMEhAA="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-69b8e9bc-326983802daece1b29f0b4ca;Parent=405bf3747a8493bc;Sampled=0;Lineage=1:133a49a5:0"}],"cookie":[],"body":"{\n    \"accountId\": \"429134563\",\n    \"transactions\": [\n        {\n            \"transactionId\": \"txn_1773694940975_r10b6fyzm\",\n            \"type\": \"CREDIT\",\n            \"category\": \"PIX_IN\",\n            \"amount\": 2.56,\n            \"balanceAfter\": 901.6,\n            \"title\": \"PIX recebido de Empresa Exemplo LTDA\",\n            \"paymentMethod\": \"PIX\",\n            \"chargeId\": null,\n            \"subscriptionId\": null,\n            \"endToEndId\": \"E13935893202603162102IfDcitXf0zO\",\n            \"counterparty\": {\n                \"name\": \"Empresa Exemplo LTDA\",\n                \"bank\": \"13935893\",\n                \"taxId\": \"37134852000458\",\n                \"account\": \"410900056\"\n            },\n            \"referenceId\": \"E139389320260316202IfDyytXf0zO\",\n            \"description\": \"PIX recebido direto\",\n            \"createdAt\": \"2026-03-16T21:02:20.975Z\"\n        },\n        {\n            \"transactionId\": \"txn_1773718528326_449bqmhm7\",\n            \"type\": \"DEBIT\",\n            \"category\": \"WITHDRAWAL\",\n            \"amount\": 1,\n            \"balanceAfter\": 929.85,\n            \"title\": \"Saque PIX\",\n            \"paymentMethod\": \"PIX\",\n            \"chargeId\": null,\n            \"subscriptionId\": null,\n            \"endToEndId\": \"E13935893202563270335KF9O0GDVVIz\",\n            \"counterparty\": null,\n            \"referenceId\": \"f7d1e875-7096-4fa8-992d-0c81a09f91c0\",\n            \"description\": \"Saque / transferência PIX\",\n            \"createdAt\": \"2026-03-17T03:35:28.326Z\"\n        }\n    ],\n    \"nextPageToken\": \"eyJTSyI6IjIwMjYtMDMtMTVUMjM6NTk6MzMuMDcxWiN0eG5fMTc3MzYxOTE3MzA3MV8zb3JpcjNjYnciLCJhY2NvdW50SWQiOiI0MjkxMzEyMTIifQ\",\n    \"hasMore\": true\n}"}]},{"name":"Extrato conta master","request":{"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/transactions?type=CREDIT&category=PAYMENT&dateFrom=2026-03-01T00:00:00Z&dateTo=2026-03-16T23:00:00Z&limit=5&nextPageToken=eyJTSyI6IjIwMjYtMDMtMTRUMjM6MjM6MzYuMDk2WiN0eG5fMTc3MzUzMDYxNjA5Nl8zOXdmbTk5aTQiLCJhY2NvdW50SWQiOiI0MjkxMzEyMTIifQ","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","transactions"],"query":[{"key":"type","value":"CREDIT","description":"optional - CREDIT ou DEBIT"},{"key":"category","value":"PAYMENT","description":"optional - PAYMENT, PIX_IN, WITHDRAWAL, etc."},{"key":"dateFrom","value":"2026-03-01T00:00:00Z","description":"optional - Data início (ISO 8601)"},{"key":"dateTo","value":"2026-03-16T23:00:00Z","description":"optional - Data fim (ISO 8601)"},{"key":"limit","value":"5","description":"optional - 1-100, default 50"},{"key":"nextPageToken","value":"eyJTSyI6IjIwMjYtMDMtMTRUMjM6MjM6MzYuMDk2WiN0eG5fMTc3MzUzMDYxNjA5Nl8zOXdmbTk5aTQiLCJhY2NvdW50SWQiOiI0MjkxMzEyMTIifQ","description":"optional - Token de paginação"}]},"description":"@scopes wallet/read\n\n@top\n\nCom esta funcionalidade você pode isualizar movimentações na sua conta"},"response":[{"name":"Sucesso","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{VALIDAPAY_PRD_URL}}/v1/wallet/transactions?type=CREDIT&dateFrom=2026-03-01T00:00:00Z&dateTo=2026-03-16T23:00:00Z&limit=5","host":["{{VALIDAPAY_PRD_URL}}"],"path":["v1","wallet","transactions"],"query":[{"key":"accountId","value":"460851686","description":"required - ID da subconta a consultar","disabled":true},{"key":"type","value":"CREDIT","description":"optional - CREDIT ou DEBIT"},{"key":"category","value":"PAYMENT","description":"optional - PAYMENT, PIX_IN, WITHDRAWAL, etc.","disabled":true},{"key":"dateFrom","value":"2026-03-01T00:00:00Z","description":"optional - Data início (ISO 8601)"},{"key":"dateTo","value":"2026-03-16T23:00:00Z","description":"optional - Data fim (ISO 8601)"},{"key":"limit","value":"5","description":"optional - 1-100, default 50"},{"key":"nextPageToken","value":"eyJTSyI6IjIwMjYtMDMtMTRUMjM6MjM6MzYuMDk2WiN0eG5fMTc3MzUzMDYxNjA5Nl8zOXdmbTk5aTQiLCJhY2NvdW50SWQiOiI0MjkxMzEyMTIifQ","description":"optional - Token de paginação","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Tue, 17 Mar 2026 05:42:20 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"2244"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"d121c426-a1b5-49cf-9dd5-3926475f45aa"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"aWl1gHMyoAMEhAA="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-69b8e9bc-326983802daece1b29f0b4ca;Parent=405bf3747a8493bc;Sampled=0;Lineage=1:133a49a5:0"}],"cookie":[],"body":"{\n    \"accountId\": \"429134563\",\n    \"transactions\": [\n        {\n            \"transactionId\": \"txn_1773694940975_r10b6fyzm\",\n            \"type\": \"CREDIT\",\n            \"category\": \"PIX_IN\",\n            \"amount\": 2.56,\n            \"balanceAfter\": 901.6,\n            \"title\": \"PIX recebido de Empresa Exemplo LTDA\",\n            \"paymentMethod\": \"PIX\",\n            \"chargeId\": null,\n            \"subscriptionId\": null,\n            \"endToEndId\": \"E13935893202603162102IfDcitXf0zO\",\n            \"counterparty\": {\n                \"name\": \"Empresa Exemplo LTDA\",\n                \"bank\": \"13935893\",\n                \"taxId\": \"37134852000458\",\n                \"account\": \"410900056\"\n            },\n            \"referenceId\": \"E139389320260316202IfDyytXf0zO\",\n            \"description\": \"PIX recebido direto\",\n            \"createdAt\": \"2026-03-16T21:02:20.975Z\"\n        },\n        {\n            \"transactionId\": \"txn_1773718528326_449bqmhm7\",\n            \"type\": \"DEBIT\",\n            \"category\": \"WITHDRAWAL\",\n            \"amount\": 1,\n            \"balanceAfter\": 929.85,\n            \"title\": \"Saque PIX\",\n            \"paymentMethod\": \"PIX\",\n            \"chargeId\": null,\n            \"subscriptionId\": null,\n            \"endToEndId\": \"E13935893202563270335KF9O0GDVVIz\",\n            \"counterparty\": null,\n            \"referenceId\": \"f7d1e875-7096-4fa8-992d-0c81a09f91c0\",\n            \"description\": \"Saque / transferência PIX\",\n            \"createdAt\": \"2026-03-17T03:35:28.326Z\"\n        }\n    ],\n    \"nextPageToken\": \"eyJTSyI6IjIwMjYtMDMtMTVUMjM6NTk6MzMuMDcxWiN0eG5fMTc3MzYxOTE3MzA3MV8zb3JpcjNjYnciLCJhY2NvdW50SWQiOiI0MjkxMzEyMTIifQ\",\n    \"hasMore\": true\n}"}]}]},{"name":"Devoluções","item":[{"name":"Devolução Pix","item":[{"name":"Criar devolução PIX","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n  \"accountId\": \"459013777\",\n  \"endToEndId\": \"E003603052026032511186a4f4cdf139\",\n  \"amount\": 1.00,\n  \"reason\": \"CUSTOMER_REQUEST\",\n  \"chargeId\": \"cha_1774437468463_4hj927ips\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/wallet/refunds","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","refunds"]},"description":"@scopes wallet/write\n\n@top\n\nCria uma **devolução PIX** a partir do `endToEndId` da transação original. A devolução pode ser parcial ou total.\n\n> ⚠️ **Atenção:** o campo `reason` (motivo da devolução) é **obrigatório**.\n\nValores aceitos para `reason`:\n\n- `CUSTOMER_REQUEST` — solicitação do cliente\n- `FRAUD` — suspeita de fraude\n- `BANK_ERROR` — erro bancário\n- `PIX_CHANGE_ERROR` — erro na transação\n\nA devolução nasce em geral como `PROCESSING`. Guarde o `refundId` retornado e acompanhe a confirmação pela rota **Consultar status da devolução PIX** (`GET /v1/wallet/refunds`).\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `accountId` | não | Número da subconta. Se omitido, opera na conta principal. |\n| `endToEndId` | sim | EndToEndId da transação PIX original. |\n| `amount` | sim | Valor da devolução (parcial ou total). |\n| `reason` | sim | Um de: BANK_ERROR, FRAUD, CUSTOMER_REQUEST, PIX_CHANGE_ERROR. |\n| `chargeId` | não | ID da charge associada. |"},"response":[{"name":"Sucesso","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n  \"accountId\": \"459013777\",\n  \"endToEndId\": \"E003603052026032511186a4f4cdf139\",\n  \"amount\": 1.00,\n  \"reason\": \"CUSTOMER_REQUEST\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/wallet/refunds","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","refunds"]}},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Wed, 25 Mar 2026 11:25:18 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"289"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"4f06a352-2983-4262-8a24-8b90ed3ea1e0"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"axvkEHy_IAMEb5g="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-69c3c619-7c3f89f6352551995595c955;Parent=5dcc357b81eb696d;Sampled=0;Lineage=1:133a49a5:0"}],"cookie":[],"body":"{\n    \"refundId\": \"ref_1774437918293_jm2hen5y7\",\n    \"status\": \"PROCESSING\",\n    \"amount\": 1,\n    \"reason\": \"CUSTOMER_REQUEST\",\n    \"endToEndId\": \"E003603052026032511186a4f4cdf139\",\n    \"returnIdentification\": \"D13935893202603251125zbRSLI3lqPH\",\n    \"chargeId\": \"cha_1774437468463_4hj927ips\",\n    \"createdAt\": \"2026-03-25T11:25:18.293Z\"\n}"},{"name":"Não autorizado","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n  \"accountId\": \"470084294\",\n  \"endToEndId\": \"E003603052026032511186a4f4cdf139\",\n  \"amount\": 1.00,\n  \"reason\": \"CUSTOMER_REQUEST\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/wallet/refunds","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","refunds"]}},"status":"Unauthorized","code":401,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Wed, 25 Mar 2026 11:28:25 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"140"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"a4f1a3c2-11b0-4797-a509-5a8ea8d5001f"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Content-Type,Authorization"},{"key":"x-amz-apigw-id","value":"axwB-El6IAMEY_w="},{"key":"Access-Control-Allow-Methods","value":"GET,POST,PUT,DELETE,OPTIONS"},{"key":"X-Amzn-Trace-Id","value":"Root=1-69c3c6d9-7e3038d76951f98207b12dc5;Parent=16427ac7fd259b88;Sampled=0;Lineage=1:133a49a5:0"}],"cookie":[],"body":"{\n    \"error\": {\n        \"message\": \"Subconta nao pertence a esta conta\",\n        \"code\": \"OWNERSHIP_MISMATCH\",\n        \"details\": null,\n        \"timestamp\": \"2026-03-25T11:28:25.397Z\"\n    }\n}"}]},{"name":"Consultar status da devolução PIX","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/refunds?refundId=ref_1774531490865_bq4e8v12x","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","refunds"],"query":[{"key":"refundId","value":"ref_1774531490865_bq4e8v12x","description":"optional - Detalhe/polling de uma devolução específica"},{"key":"returnIdentification","value":"D13935893202603261324C5jA3zE3V6J","description":"optional - Detalhe pelo ID de devolução PIX","disabled":true},{"key":"endToEndId","value":"E0036030520260326132336e2f8787c4","description":"optional - Lista as devoluções do PIX original","disabled":true},{"key":"chargeId","value":"cha_1774530966959_frgj3ptax","description":"optional - Lista as devoluções da cobrança","disabled":true},{"key":"accountId","value":"429131213","description":"optional - (M2M) Filtra pela subconta","disabled":true}]},"description":"@scopes wallet/read\n\n@top\n\nConsulta se uma **devolução PIX** foi confirmada.\n\nNão use o status da cobrança (`REFUNDED` / `PARTIALLY_REFUNDED`) para saber se o estorno foi confirmado — use o refund:\n\n- `status === \"CONFIRMED\"` (ou `success === true`): estorno confirmado\n- `status === \"PROCESSING\"`: ainda aguardando\n- `status === \"ERROR\"`: falhou (`error` pode vir preenchido)\n\nModos de uso:\n\n- Informe `refundId` (ou `returnIdentification`) para o detalhe/polling de uma devolução específica.\n- Informe `endToEndId` do PIX original para consultar as devoluções daquele pagamento.\n- MasterAccounts podem consultar uma subconta informando `accountId`.\n\nPrecedência: `refundId` > `returnIdentification` > `endToEndId` > `chargeId`.\n\n> ℹ️ Polling sugerido: 2–5s com timeout (60–120s)."},"response":[{"name":"Item único (por refundId)","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/refunds","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","refunds"]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"body":"{\n    \"refundId\": \"ref_1774531490865_bq4e8v12x\",\n    \"accountId\": \"429131212\",\n    \"status\": \"CONFIRMED\",\n    \"success\": true,\n    \"amount\": 100.00,\n    \"reason\": \"CUSTOMER_REQUEST\",\n    \"chargeId\": \"cha_1774530966959_frgj3ptax\",\n    \"originalEndToEndId\": \"E0036030520260326132336e2f8787c4\",\n    \"returnIdentification\": \"D13935893202603261324C5jA3zE3V6J\",\n    \"providerChargeId\": null,\n    \"paymentType\": null,\n    \"splitReversals\": [],\n    \"error\": null,\n    \"createdAt\": \"2026-03-26T13:24:52.106Z\",\n    \"updatedAt\": \"2026-03-26T13:24:57.553Z\"\n}"},{"name":"404 REFUND_NOT_FOUND","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/refunds","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","refunds"]}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"body":"{\n    \"error\": {\n        \"message\": \"Refund não encontrado\",\n        \"code\": \"REFUND_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-08-05T12:00:00.000Z\"\n    }\n}"}]}]},{"name":"Estorno Cartão","item":[{"name":"Criar estorno de cartão","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n  \"accountId\": \"459013777\",\n  \"chargeId\": \"cha_1774530966959_frgj3ptax\",\n  \"amount\": 100.00,\n  \"reason\": \"CUSTOMER_REQUEST\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/wallet/refunds","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","refunds"]},"description":"@scopes wallet/write\n\n@top\n\nCria um **estorno de cartão de crédito** a partir do `chargeId` da cobrança original. O estorno pode ser parcial ou total.\n\n> ℹ️ Para cartão, o estorno pode retornar `CONFIRMED` na hora, quando a confirmação vem imediatamente — nesse caso o polling não é necessário (`success` já vem `true`).\n\nSe vier `PROCESSING`, guarde o `refundId` e acompanhe pela rota **Consultar status do estorno** (`GET /v1/wallet/refunds`).\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `accountId` | não | Número da subconta. Se omitido, opera na conta principal. |\n| `chargeId` | sim | ID da cobrança de cartão a ser estornada. |\n| `amount` | sim | Valor do estorno (parcial ou total). |\n| `reason` | não | Motivo do estorno. |"},"response":[{"name":"Sucesso","originalRequest":{"method":"POST","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/refunds","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","refunds"]}},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"body":"{\n    \"refundId\": \"ref_1774531490865_bq4e8v12x\",\n    \"status\": \"CONFIRMED\",\n    \"success\": true,\n    \"amount\": 100,\n    \"reason\": \"CUSTOMER_REQUEST\",\n    \"chargeId\": \"cha_1774530966959_frgj3ptax\",\n    \"providerChargeId\": \"prov_ch_9f8a7b6c\",\n    \"paymentType\": \"CREDIT_CARD\",\n    \"createdAt\": \"2026-03-26T13:24:52.106Z\"\n}"}]},{"name":"Consultar status do estorno","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/refunds?refundId=ref_1774531490865_bq4e8v12x","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","refunds"],"query":[{"key":"refundId","value":"ref_1774531490865_bq4e8v12x","description":"optional - Detalhe/polling de um estorno específico"},{"key":"chargeId","value":"cha_1774530966959_frgj3ptax","description":"optional - Lista os estornos da cobrança de cartão","disabled":true},{"key":"accountId","value":"429131213","description":"optional - (M2M) Filtra pela subconta","disabled":true}]},"description":"@scopes wallet/read\n\n@top\n\nConsulta se um **estorno de cartão** foi confirmado.\n\nUse o refund (não o status da cobrança) para confirmar:\n\n- `status === \"CONFIRMED\"` (ou `success === true`): estorno confirmado\n- `status === \"PROCESSING\"`: ainda aguardando\n- `status === \"ERROR\"`: falhou (`error` pode vir preenchido)\n\nModos de uso:\n\n- Informe `refundId` para o detalhe/polling de um estorno específico.\n- Informe `chargeId` para consultar os estornos daquela cobrança de cartão.\n- MasterAccounts podem consultar uma subconta informando `accountId`.\n\n> ℹ️ No estorno de cartão a resposta traz `paymentType: \"CREDIT_CARD\"` e o `providerChargeId` da transação."},"response":[{"name":"Item único (por refundId)","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/refunds","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","refunds"]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"body":"{\n    \"refundId\": \"ref_1774531490865_bq4e8v12x\",\n    \"accountId\": \"429131212\",\n    \"status\": \"CONFIRMED\",\n    \"success\": true,\n    \"amount\": 100.00,\n    \"reason\": \"CUSTOMER_REQUEST\",\n    \"chargeId\": \"cha_1774530966959_frgj3ptax\",\n    \"originalEndToEndId\": null,\n    \"returnIdentification\": null,\n    \"providerChargeId\": \"prov_ch_9f8a7b6c\",\n    \"paymentType\": \"CREDIT_CARD\",\n    \"splitReversals\": [],\n    \"error\": null,\n    \"createdAt\": \"2026-03-26T13:24:52.106Z\",\n    \"updatedAt\": \"2026-03-26T13:24:57.553Z\"\n}"},{"name":"404 REFUND_NOT_FOUND","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/wallet/refunds","protocol":"https","host":["api","validapay","com","br"],"path":["v1","wallet","refunds"]}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"body":"{\n    \"error\": {\n        \"message\": \"Refund não encontrado\",\n        \"code\": \"REFUND_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-08-05T12:00:00.000Z\"\n    }\n}"}]}]}]},{"name":"Autenticação","request":{"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[{"key":"grant_type","value":"client_credentials","description":"required - Tipo de autenticação. Valor fixo: client_credentials","type":"text"},{"key":"client_id","value":"{{client_id}}","type":"text"},{"key":"client_secret","value":"{{client_secret}}","type":"text"},{"key":"scope","value":"{{scope}}","type":"text"}]},"url":{"raw":"https://oauth2.validapay.com.br/auth/token","protocol":"https","host":["oauth2","validapay","com","br"],"path":["auth","token"],"query":[{"key":"","value":null,"disabled":true},{"key":"","value":null,"disabled":true}]}},"response":[{"name":"200","originalRequest":{"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[{"key":"grant_type","value":"client_credentials","type":"text"},{"key":"client_id","value":"zxjqfn6gyrbmty8e0lcd2bxf6g856z","type":"text"},{"key":"client_secret","value":"RsvneD8lefY0zqAQIQan1Ctd1UEO6t6IE4j89gKD","type":"text"},{"key":"scope","value":"account/read","type":"text"}]},"url":{"raw":"https://dev.validapay.com.br/auth/token","protocol":"https","host":["dev","validapay","com","br"],"path":["auth","token"]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Wed, 19 Nov 2025 09:46:18 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"914"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"08683db0-ae01-40d0-87a6-dd42fcf4315a"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"x-amz-apigw-id","value":"USO8YEx3mjQEXhA="},{"key":"X-Amzn-Trace-Id","value":"Root=1-691d91e8-0ff5149e3a2e23f76e529cb9;Parent=220b7b541e998ca6;Sampled=0;Lineage=1:aac62a29:0"}],"cookie":[],"body":"{\n    \"access_token\": \"eyJraWQiOiJleGVtcGxvIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJ0b2tlbl91c2UiOiJhY2Nlc3MiLCJzY29wZSI6ImFjY291bnQvcmVhZCIsImNsaWVudF9pZCI6ImV4ZW1wbG9jbGllbnRpZDEyMzQ1Njc4OTAiLCJpc3MiOiJodHRwczovL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tL3VzLWVhc3QtMV9FWEVNUExPIiwiZXhwIjoxOTAwMDAwMDAwLCJpYXQiOjE4OTk5OTY0MDB9.ASSINATURA_DE_EXEMPLO\",\n    \"expires_in\": 3600,\n    \"token_type\": \"Bearer\"\n}"}]},{"name":"Clientes","item":[{"name":"Criar Cliente","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"url":{"raw":"https://api.validapay.com.br/v1/customers","protocol":"https","host":["api","validapay","com","br"],"path":["v1","customers"]},"description":"@scopes customers/write\n\n@top\n\nCadastra um cliente na sua conta a partir do CPF/CNPJ, com endereço opcional.\n\nO documento é a chave do cliente dentro da conta e não pode ser alterado depois. Por padrão, se já existir um cliente com o mesmo documento, a API devolve 200 com o cadastro existente em vez de duplicar. Envie upsert: true para que a tentativa de recadastrar retorne erro 400 (CUSTOMER_ALREADY_EXISTS).\n\nQuando o endereço é informado, o código IBGE do município (cityCode) é resolvido automaticamente a partir do CEP — necessário para emissão de NFS-e.\n\nCase de uso:\n\n_Como plataforma, quero cadastrar meus clientes junto com o endereço de cobrança, para depois gerar assinaturas e cobranças sem redigitar os dados a cada venda._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `name` | sim | Nome completo ou razão social |\n| `document` | sim | CPF (11) ou CNPJ (14), apenas dígitos |\n| `phone` | sim | E.164 com DDI 55 |\n| `email` | não |  |\n| `upsert` | não | true retorna erro 400 se o documento já existir (default false) |\n| `address` | não |  |\n| `address.zipCode` | sim | 8 dígitos, apenas números |\n| `address.street` | sim |  |\n| `address.number` | sim |  |\n| `address.complement` | não |  |\n| `address.neighborhood` | sim |  |\n| `address.city` | sim |  |\n| `address.state` | sim | UF com 2 letras |","body":{"mode":"raw","raw":"{\n  \"name\": \"Alexandre Souza\",\n  \"document\": \"11144477735\",\n  \"phone\": \"5511987654321\",\n  \"email\": \"alexandre@exemplo.com.br\",\n  \"upsert\": false,\n  \"address\": {\n    \"zipCode\": \"01310100\",\n    \"street\": \"Avenida Paulista\",\n    \"number\": \"1000\",\n    \"complement\": \"Sala 5\",\n    \"neighborhood\": \"Bela Vista\",\n    \"city\": \"São Paulo\",\n    \"state\": \"SP\"\n  }\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"201","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"customer\": {\n    \"customerId\": \"cus_xxx\",\n    \"id\": \"cus_xxx\",\n    \"name\": \"Alexandre Souza\",\n    \"document\": \"11144477735\",\n    \"email\": \"alexandre@exemplo.com.br\",\n    \"phone\": \"5511987654321\",\n    \"accountId\": \"460851686\",\n    \"status\": \"ACTIVE\",\n    \"createdAt\": \"2026-08-28T12:00:00.000Z\"\n  }\n}","cookie":[]},{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"customer\": {\n    \"customerId\": \"cus_xxx\",\n    \"document\": \"11144477735\",\n    \"name\": \"Alexandre Souza\"\n  }\n}","cookie":[]},{"name":"400","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Já existe um cliente cadastrado com este documento\",\n        \"code\": \"CUSTOMER_ALREADY_EXISTS\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Listar Clientes","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/customers?limit=15&lastKey=&search=&document=&status=&startDate=&endDate=","protocol":"https","host":["api","validapay","com","br"],"path":["v1","customers"],"query":[{"key":"limit","value":"15","description":"Quantidade de itens por página (default 15) - optional","disabled":false},{"key":"lastKey","value":"","description":"Cursor da próxima página, em base64, retornado em pagination.lastKey - optional","disabled":false},{"key":"search","value":"","description":"Busca parcial por nome, e-mail ou documento - optional","disabled":false},{"key":"document","value":"","description":"Filtro por CPF/CNPJ exato, apenas dígitos - optional","disabled":false},{"key":"status","value":"","description":"ACTIVE | INACTIVE | BLOCKED - optional","disabled":false},{"key":"startDate","value":"","description":"Data inicial de criação (ISO 8601) - optional","disabled":false},{"key":"endDate","value":"","description":"Data final de criação (ISO 8601) - optional","disabled":false}]},"description":"@scopes customers/read\n\n@top\n\nLista os clientes cadastrados na sua conta, com busca por texto e paginação por cursor.\n\nO parâmetro search faz busca parcial simultânea em nome, e-mail e documento — é o filtro indicado para uma tela de seleção de cliente, onde o usuário pode digitar qualquer um dos três. Já document faz correspondência exata e deve ser usado quando o CPF/CNPJ completo já é conhecido.\n\nA paginação é por cursor: quando houver mais páginas, pagination.lastKey vem preenchido; repita a chamada enviando esse valor em lastKey, mantendo os mesmos filtros. Quando lastKey vier null, não há mais páginas.\n\nCase de uso:\n\n_Como integrador, quero buscar um cliente já cadastrado por nome, e-mail ou CPF/CNPJ, para preencher automaticamente os dados na hora de criar uma nova cobrança._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"items\": [\n    {\n      \"customerId\": \"cus_xxx\",\n      \"name\": \"Alexandre Souza\",\n      \"document\": \"11144477735\",\n      \"email\": \"alexandre@exemplo.com.br\",\n      \"phone\": \"5511987654321\",\n      \"status\": \"ACTIVE\",\n      \"createdAt\": \"2026-08-28T12:00:00.000Z\",\n      \"subscriptions\": []\n    }\n  ],\n  \"pagination\": {\n    \"total\": 128,\n    \"totalPages\": 9,\n    \"limit\": 15,\n    \"hasMore\": true,\n    \"lastKey\": \"eyJQSyI6...=\"\n  }\n}","cookie":[]}]},{"name":"Buscar Cliente por Documento","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/customers?lookupDocument=11144477735","protocol":"https","host":["api","validapay","com","br"],"path":["v1","customers"],"query":[{"key":"lookupDocument","value":"11144477735","description":"CPF (11) ou CNPJ (14), apenas dígitos - required","disabled":false}]},"description":"@scopes customers/read\n\n@top\n\nBusca direta de um único cliente pelo CPF/CNPJ exato, retornando junto o endereço padrão dele.\n\nDiferente de Listar Clientes, esta chamada não devolve lista nem paginação: retorna o objeto do cliente e o endereço em uma única resposta, pronto para preencher um formulário. Quando o documento não está cadastrado, a resposta é 200 com customer e address em null — não é erro.\n\nCase de uso:\n\n_Como checkout próprio, quero consultar o CPF digitado pelo comprador e, se ele já for cliente, preencher nome, e-mail, telefone e endereço automaticamente._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"customer\": {\n    \"customerId\": \"cus_xxx\",\n    \"name\": \"Alexandre Souza\",\n    \"document\": \"11144477735\",\n    \"email\": \"alexandre@exemplo.com.br\",\n    \"phone\": \"5511987654321\",\n    \"status\": \"ACTIVE\"\n  },\n  \"address\": {\n    \"zipCode\": \"01310100\",\n    \"street\": \"Avenida Paulista\",\n    \"number\": \"1000\",\n    \"complement\": \"Sala 5\",\n    \"neighborhood\": \"Bela Vista\",\n    \"city\": \"São Paulo\",\n    \"state\": \"SP\",\n    \"cityCode\": \"3550308\"\n  }\n}","cookie":[]},{"name":"200 (não encontrado)","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"customer\": null,\n  \"address\": null\n}","cookie":[]}]},{"name":"Detalhar Cliente","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/customers/:customerId","protocol":"https","host":["api","validapay","com","br"],"path":["v1","customers",":customerId"]},"description":"@scopes customers/read\n\n@top\n\nRetorna os dados completos de um cliente, incluindo todos os endereços cadastrados e o histórico de assinaturas.\n\nCada assinatura vem acompanhada dos itens, dos ciclos de cobrança e das faturas e cobranças de cada ciclo. É a visão consolidada usada na tela de detalhe do cliente.\n\nCase de uso:\n\n_Como atendente, quero ver tudo que um cliente possui — assinaturas, ciclos e faturas — em uma única consulta, para responder a um contato de suporte._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"customer\": {\n    \"customerId\": \"cus_xxx\",\n    \"name\": \"Alexandre Souza\",\n    \"document\": \"11144477735\",\n    \"status\": \"ACTIVE\"\n  },\n  \"addresses\": [\n    {\n      \"zipCode\": \"01310100\",\n      \"street\": \"Avenida Paulista\",\n      \"number\": \"1000\",\n      \"city\": \"São Paulo\",\n      \"state\": \"SP\",\n      \"isDefault\": true\n    }\n  ],\n  \"subscriptions\": []\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Cliente não encontrado\",\n        \"code\": \"CUSTOMER_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Atualizar Cliente","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"PATCH","header":[],"url":{"raw":"https://api.validapay.com.br/v1/customers/:customerId","protocol":"https","host":["api","validapay","com","br"],"path":["v1","customers",":customerId"]},"description":"@scopes customers/write\n\n@top\n\nAtualiza os dados de um cliente. Envie apenas os campos que deseja alterar.\n\nO documento não pode ser alterado: enviar um CPF/CNPJ diferente do atual retorna erro 400 (DOCUMENT_UPDATE_NOT_ALLOWED). Quando o endereço é enviado, ele substitui o endereço padrão do cliente.\n\nCase de uso:\n\n_Como plataforma, quero atualizar o e-mail e o telefone de um cliente que mudou de contato, sem recriar o cadastro._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `name` | não |  |\n| `email` | não |  |\n| `phone` | não | E.164 com DDI 55 |\n| `address` | não | substitui o endereço padrão |\n| `address.zipCode` | sim |  |\n| `address.street` | sim |  |\n| `address.number` | sim |  |\n| `address.complement` | não |  |\n| `address.neighborhood` | sim |  |\n| `address.city` | sim |  |\n| `address.state` | sim |  |","body":{"mode":"raw","raw":"{\n  \"name\": \"Alexandre Souza Silva\",\n  \"email\": \"novo@exemplo.com.br\",\n  \"additionalEmails\": [\"financeiro@exemplo.com.br\"],\n  \"phone\": \"5511987654321\",\n  \"address\": {\n    \"zipCode\": \"01310100\",\n    \"street\": \"Avenida Paulista\",\n    \"number\": \"2000\",\n    \"complement\": \"Andar 3\",\n    \"neighborhood\": \"Bela Vista\",\n    \"city\": \"São Paulo\",\n    \"state\": \"SP\"\n  }\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"customer\": {\n    \"customerId\": \"cus_xxx\",\n    \"name\": \"Alexandre Souza Silva\",\n    \"email\": \"novo@exemplo.com.br\",\n    \"phone\": \"5511987654321\"\n  }\n}","cookie":[]},{"name":"400","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"O documento do cliente não pode ser alterado\",\n        \"code\": \"DOCUMENT_UPDATE_NOT_ALLOWED\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Remover Cliente","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"DELETE","header":[],"url":{"raw":"https://api.validapay.com.br/v1/customers/:customerId","protocol":"https","host":["api","validapay","com","br"],"path":["v1","customers",":customerId"]},"description":"@scopes customers/delete\n\n@top\n\nRemove um cliente da sua conta.\n\nA exclusão é bloqueada quando o cliente possui assinaturas recorrentes vinculadas, retornando erro 400 (CUSTOMER_HAS_ACTIVE_SUBSCRIPTIONS). Cancele as assinaturas antes de excluir.\n\nCase de uso:\n\n_Como plataforma, quero remover um cadastro criado por engano, garantindo que clientes com assinaturas ativas não sejam apagados por acidente._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true\n}","cookie":[]},{"name":"400","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Cliente possui assinaturas vinculadas e não pode ser excluído\",\n        \"code\": \"CUSTOMER_HAS_ACTIVE_SUBSCRIPTIONS\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]}]},{"name":"Assinaturas","item":[{"name":"Listar Assinaturas","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/subscriptions?limit=15&lastKey=&startDate=&endDate=&status=&search=&document=&paymentMethod=&priceId=&productId=","protocol":"https","host":["api","validapay","com","br"],"path":["v1","subscriptions"],"query":[{"key":"limit","value":"15","description":"Quantidade de itens por página (default 15) - optional","disabled":false},{"key":"lastKey","value":"","description":"Cursor de paginação em base64 retornado na resposta anterior - optional","disabled":false},{"key":"startDate","value":"","description":"Filtro por createdAt. ISO 8601 recomendado (ex: 2026-03-10T00:00:00.000Z). YYYY-MM-DD aceito - optional","disabled":false},{"key":"endDate","value":"","description":"Filtro por createdAt. ISO 8601 com fim do dia (ex: 2026-03-10T23:59:59.999Z). YYYY-MM-DD pode excluir registros do mesmo dia com horário - optional","disabled":false},{"key":"status","value":"","description":"Filtro por status (lista separada por vírgula): PENDING, AWAITING_PAYMENT, ACTIVE, TRIALING, PAST_DUE, PAUSED, CANCELED, INCOMPLETE - optional","disabled":false},{"key":"search","value":"","description":"Busca por nome ou documento do cliente - optional","disabled":false},{"key":"document","value":"","description":"Filtro por CPF ou CNPJ do cliente - optional","disabled":false},{"key":"paymentMethod","value":"","description":"Filtro por método: CREDIT_CARD, PIX, BOLETO ou PIX_AUTOMATICO. Alias aceito: paymentType - optional","disabled":false},{"key":"priceId","value":"","description":"Filtro por ID do preço - optional","disabled":false},{"key":"productId","value":"","description":"Filtro por ID do produto - optional","disabled":false}]},"description":"@scopes subscriptions/read\n\n@top\n\nLista todas as assinaturas da conta com suporte a filtros por status, cliente, método de pagamento, produto e período.\n\nUtilize o campo `lastKey` retornado na resposta para navegar entre as páginas.\n\nStatus possíveis: `PENDING`, `AWAITING_PAYMENT`, `ACTIVE`, `TRIALING`, `PAST_DUE`, `PAUSED`, `CANCELED`, `INCOMPLETE`.\n\n> Assinaturas com `interval: ONE_TIME` são excluídas automaticamente do resultado.\n\nCase de uso:\n\n_Como SaaS, quero listar todas as assinaturas ativas dos meus clientes para exibir no meu painel administrativo._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"items\": [\n    {\n      \"subscriptionId\": \"sub_xxx\",\n      \"status\": \"ACTIVE\",\n      \"interval\": \"MONTHLY\",\n      \"billingDay\": 15,\n      \"currentCycleNumber\": 3,\n      \"currentCycleAmount\": 99.9,\n      \"nextCycleChargeDate\": \"2024-02-15\",\n      \"customer\": {\n        \"customerId\": \"cus_xxx\",\n        \"name\": \"João Silva\",\n        \"email\": \"joao@email.com\"\n      },\n      \"lastCharge\": {\n        \"netAmount\": 98.91,\n        \"status\": \"PAID\"\n      }\n    }\n  ],\n  \"pagination\": {\n    \"total\": 50,\n    \"hasMore\": true,\n    \"lastKey\": \"eyJ...\"\n  }\n}","cookie":[]}]},{"name":"Buscar Assinatura","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/subscriptions/:subscriptionId","protocol":"https","host":["api","validapay","com","br"],"path":["v1","subscriptions",":subscriptionId"],"variable":[{"key":"subscriptionId","value":"sub_xxx","description":"ID da assinatura (ex: sub_xxx) - required"}]},"description":"@scopes subscriptions/read\n\n@top\n\nRetorna os detalhes completos de uma assinatura específica.\n\nA resposta inclui: `customer` (dados do cliente), `items` (itens da assinatura), `upgrades` (mudanças de plano pendentes), `billingCycles` (histórico de ciclos) e `coupon` (cupom aplicado, se houver).\n\nCase de uso:\n\n_Como SaaS, quero consultar o status e os itens de uma assinatura específica para exibir na área do cliente._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"subscriptionId\": \"sub_xxx\",\n  \"status\": \"ACTIVE\",\n  \"customer\": {},\n  \"items\": [],\n  \"upgrades\": [],\n  \"billingCycles\": [],\n  \"coupon\": null\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Assinatura não encontrada\",\n        \"code\": \"SUBSCRIPTION_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Atualizar Assinatura (Item)","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"PATCH","header":[],"url":{"raw":"https://api.validapay.com.br/v1/subscriptions/:subscriptionId","protocol":"https","host":["api","validapay","com","br"],"path":["v1","subscriptions",":subscriptionId"],"variable":[{"key":"subscriptionId","value":"sub_xxx","description":"ID da assinatura (ex: sub_xxx) - required"}]},"description":"@scopes subscriptions/write\n\n@top\n\nRealiza **upgrade ou downgrade** de um item da assinatura. Envie `old.itemId` do item atual e `new.priceId` (e opcionalmente `new.quantity`) do novo plano.\n\n> Rota **canônica** para upgrade/downgrade: **Atualizar Item** (PUT). Este PATCH delega para a mesma lógica.\n\n- **Upgrade:** gera cobrança de pro rata imediatamente (cartão) ou de forma assíncrona via webhook (PIX/boleto). O item antigo só é substituído após confirmação do pagamento.\n- **Downgrade:** a mudança é agendada para o próximo ciclo de cobrança, sem cobrança imediata.\n\nPré-condições: assinatura `ACTIVE`, `PAST_DUE` ou `AWAITING_PAYMENT`; item com status `ACTIVE`.\n\nCase de uso:\n\n_Como SaaS, quero permitir que meu cliente faça upgrade do plano Básico para o Pro no meio do ciclo, cobrando apenas a diferença proporcional._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `old` | sim |  |\n| `old.itemId` | sim | ID do item atual |\n| `new` | sim |  |\n| `new.priceId` | sim | ID do novo preço |\n| `new.quantity` | não | Nova quantidade (default 1) |","body":{"mode":"raw","raw":"{\n  \"old\": {\n    \"itemId\": \"item_xxx\"\n  },\n  \"new\": {\n    \"priceId\": \"price_yyy\",\n    \"quantity\": 2\n  }\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"type\": \"UPGRADE\",\n  \"chargeId\": \"cha_xxx\",\n  \"prorataAmount\": 45.0,\n  \"newAmount\": 100.0\n}","cookie":[]},{"name":"400","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Cartão recusado por saldo insuficiente\",\n        \"code\": \"PAYMENT_DECLINED\",\n        \"details\": {\n            \"declinedCode\": \"insufficient_funds\"\n        },\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Cancelar Item","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"PATCH","header":[],"url":{"raw":"https://api.validapay.com.br/v1/subscriptions/:subscriptionId","protocol":"https","host":["api","validapay","com","br"],"path":["v1","subscriptions",":subscriptionId"],"variable":[{"key":"subscriptionId","value":"sub_xxx","description":"ID da assinatura (ex: sub_xxx) - required"}]},"description":"@scopes subscriptions/write\n\n@top\n\nRemove um **item** da assinatura sem cancelar a assinatura inteira.\n\nEnvie apenas `old.itemId` — **não informe** o campo `new`. A ausência de `new` indica cancelamento de item.\n\nCase de uso:\n\n_Como SaaS, quero remover um add-on da assinatura do cliente mantendo o plano principal ativo._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `old` | sim |  |\n| `old.itemId` | sim | ID do item a remover |","body":{"mode":"raw","raw":"{\n  \"old\": {\n    \"itemId\": \"item_xxx\"\n  }\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"type\": \"ITEM_CANCELED\",\n  \"itemId\": \"item_xxx\"\n}","cookie":[]},{"name":"400","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"old.itemId é obrigatório\",\n        \"code\": \"MISSING_ITEM_ID\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Item não encontrado\",\n        \"code\": \"ITEM_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Cancelar Assinatura","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"DELETE","header":[],"url":{"raw":"https://api.validapay.com.br/v1/subscriptions/:subscriptionId","protocol":"https","host":["api","validapay","com","br"],"path":["v1","subscriptions",":subscriptionId"],"variable":[{"key":"subscriptionId","value":"sub_xxx","description":"ID da assinatura (ex: sub_xxx) - required"}]},"description":"@scopes subscriptions/write\n\n@top\n\nCancela uma assinatura ativa, interrompendo todas as cobranças futuras. **Rota recomendada** para cancelamento (preferir em relação ao PATCH com `action: \"cancel\"`).\n\nA assinatura é marcada como `CANCELED` imediatamente. Ciclos futuros pendentes (`PENDING`, `AWAITING_PAYMENT`) são cancelados.\n\nO campo `reason` é opcional e pode ser usado para registrar o motivo do cancelamento.\n\nCase de uso:\n\n_Como SaaS, quero cancelar a assinatura de um cliente que solicitou encerramento do serviço._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `reason` | não | Motivo do cancelamento |","body":{"mode":"raw","raw":"{\n  \"reason\": \"Cliente solicitou\"\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"message\": \"Assinatura cancelada com sucesso\",\n  \"status\": \"CANCELED\",\n  \"canceledCycles\": 2\n}","cookie":[]},{"name":"400","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Assinatura já está cancelada\",\n        \"code\": \"SUBSCRIPTION_ALREADY_CANCELED\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Assinatura não encontrada\",\n        \"code\": \"SUBSCRIPTION_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Adicionar Item","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"url":{"raw":"https://api.validapay.com.br/v1/subscriptions/:subscriptionId/items","protocol":"https","host":["api","validapay","com","br"],"path":["v1","subscriptions",":subscriptionId","items"],"variable":[{"key":"subscriptionId","value":"sub_xxx","description":"ID da assinatura (ex: sub_xxx) - required"}]},"description":"@scopes subscriptions/write\n\n@top\n\nAdiciona um novo produto ou serviço a uma assinatura já existente.\n\nInforme o `priceId` de um preço previamente cadastrado. Para assinaturas com cartão de crédito, a cobrança é processada imediatamente. Para PIX ou boleto, a resposta inclui `payment.transactionId` — a confirmação chega via **webhook**.\n\nPré-condições: assinatura `ACTIVE` ou `PAST_DUE`. Antes do 1º pagamento confirmado (`currentCycleNumber === 1`), add item retorna `400`.\n\n> `billOnNextCycle` adia a cobrança para o próximo ciclo (apenas boleto/PIX; incompatível com cartão ou `ONE_TIME`).\n\nCase de uso:\n\n_Como SaaS, quero adicionar um módulo extra (add-on) à assinatura de um cliente que já possui um plano base._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `priceId` | sim | ID do preço do item |\n| `quantity` | não | Quantidade (default 1, mínimo 1) |\n| `type` | não | RECURRING ou ONE_TIME (default RECURRING) |\n| `billOnNextCycle` | não | Adia cobrança para próximo ciclo (boleto/PIX apenas) |\n| `dueDate` | não | Vencimento do boleto/PIX de pro-rata (YYYY-MM-DD) |\n| `boletoInstructions` | não | Para assinaturas com boleto |\n| `expirationAfterDueDate` | não | Dias após vencimento (0 a 60, default 30) |","body":{"mode":"raw","raw":"{\n  \"priceId\": \"price_xxx\",\n  \"quantity\": 1,\n  \"type\": \"RECURRING\",\n  \"billOnNextCycle\": false,\n  \"dueDate\": \"2026-04-06\",\n  \"boletoInstructions\": {\n    \"fine\": 2.0,\n    \"interest\": 1.0\n  },\n  \"expirationAfterDueDate\": 30\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200 cartão","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"type\": \"ADD_ITEM\",\n  \"chargeId\": \"cha_xxx\",\n  \"amount\": 49.9,\n  \"newAmount\": 149.8\n}","cookie":[]},{"name":"200 PIX","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"type\": \"ADD_ITEM\",\n  \"paymentMethod\": \"PIX\",\n  \"chargeId\": \"cha_xxx\",\n  \"payment\": {\n    \"emvQrCode\": \"...\"\n  }\n}","cookie":[]},{"name":"400 pagamento","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Cartão recusado pela operadora\",\n        \"code\": \"PAYMENT_DECLINED\",\n        \"details\": {\n            \"declinedCode\": \"card_declined\"\n        },\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]},{"name":"400","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Assinatura não está ativa\",\n        \"code\": \"SUBSCRIPTION_NOT_ACTIVE\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Atualizar Item","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"PUT","header":[],"url":{"raw":"https://api.validapay.com.br/v1/subscriptions/:subscriptionId/items/:itemId","protocol":"https","host":["api","validapay","com","br"],"path":["v1","subscriptions",":subscriptionId","items",":itemId"],"variable":[{"key":"subscriptionId","value":"sub_xxx","description":"ID da assinatura (ex: sub_xxx) - required"},{"key":"itemId","value":"item_xxx","description":"ID do item da assinatura (ex: item_xxx) - required"}]},"description":"@scopes subscriptions/write\n\n@top\n\n**Rota canônica** para upgrade ou downgrade de plano. Altera o `priceId` ou `quantity` de um item específico.\n\nO `subscriptionId` e `itemId` vão na URL. Informe pelo menos `priceId` ou `quantity`.\n\n- **Upgrade** (`newTotal > currentTotal`): cobra pro-rata imediatamente (cartão) ou gera boleto/PIX assíncrono.\n- **Downgrade** (`newTotal <= currentTotal`): efetivado no próximo ciclo, sem cobrança imediata.\n\nPré-condições: assinatura `ACTIVE`, `PAST_DUE` ou `AWAITING_PAYMENT`; item `ACTIVE`.\n\n> Falha de pagamento retorna **400** com `PAYMENT_DECLINED` ou `PAYMENT_FAILED` (não 402).\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `priceId` | não | Pelo menos priceId ou quantity é obrigatório |\n| `quantity` | não |  |\n| `dueDate` | não | Vencimento do boleto/PIX de pro-rata (YYYY-MM-DD) |\n| `boletoInstructions` | não | Juros, multa e desconto do boleto |\n| `expirationAfterDueDate` | não | Dias após vencimento (0 a 60, default 30) |","body":{"mode":"raw","raw":"{\n  \"priceId\": \"price_yyy\",\n  \"quantity\": 2,\n  \"dueDate\": \"2026-04-06\",\n  \"boletoInstructions\": {\n    \"fine\": 2.0,\n    \"interest\": 1.0\n  },\n  \"expirationAfterDueDate\": 30\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200 upgrade","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"type\": \"UPGRADE\",\n  \"chargeId\": \"cha_xxx\",\n  \"prorataAmount\": 33.5,\n  \"newAmount\": 199.9\n}","cookie":[]},{"name":"200 downgrade","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"type\": \"DOWNGRADE\",\n  \"effectiveAt\": \"2024-02-01\",\n  \"newAmount\": 59.9\n}","cookie":[]},{"name":"400 pagamento","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Cartão recusado por saldo insuficiente\",\n        \"code\": \"PAYMENT_DECLINED\",\n        \"details\": {\n            \"declinedCode\": \"insufficient_funds\"\n        },\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Item não encontrado\",\n        \"code\": \"ITEM_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Calcular Pro Rata","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"url":{"raw":"https://api.validapay.com.br/v1/subscriptions/:subscriptionId/prorata","protocol":"https","host":["api","validapay","com","br"],"path":["v1","subscriptions",":subscriptionId","prorata"],"variable":[{"key":"subscriptionId","value":"sub_xxx","description":"ID da assinatura (ex: sub_xxx) - required"}]},"description":"@scopes subscriptions/read\n\n@top\n\nCalcula o valor de pro rata para uma troca de plano **sem efetuar cobrança**.\n\nÚtil para exibir ao cliente o valor exato da mudança antes de confirmar o upgrade. O cálculo considera os dias restantes do ciclo atual.\n\nEnvie `old` com o preço/quantidade atuais e `new` com o preço/quantidade desejados.\n\nCase de uso:\n\n_Como SaaS, quero mostrar na interface \"Você pagará R$ 45,48 hoje pela diferença proporcional\" antes do cliente confirmar o upgrade._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `old` | sim |  |\n| `old.priceId` | sim | Preço atual |\n| `old.quantity` | não |  |\n| `new` | sim |  |\n| `new.priceId` | sim | Novo preço |\n| `new.quantity` | não |  |","body":{"mode":"raw","raw":"{\n  \"old\": {\n    \"priceId\": \"price_xxx\",\n    \"quantity\": 1\n  },\n  \"new\": {\n    \"priceId\": \"price_yyy\",\n    \"quantity\": 1\n  }\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"subscriptionId\": \"sub_xxx\",\n  \"currentAmount\": 99.9,\n  \"newAmount\": 199.9,\n  \"prorataAmount\": 45.48,\n  \"remainingDays\": 15,\n  \"cycleDays\": 31,\n  \"currentCredit\": 48.34,\n  \"nextCycleChargeDate\": \"2024-02-15\"\n}","cookie":[]},{"name":"404 old","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Preço antigo não encontrado\",\n        \"code\": \"OLD_PRICE_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]},{"name":"404 new","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Preço novo não encontrado\",\n        \"code\": \"NEW_PRICE_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]},{"name":"404 sub","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Assinatura não encontrada\",\n        \"code\": \"SUBSCRIPTION_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]}]},{"name":"Notas Fiscais","item":[{"name":"Listar Notas Fiscais","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas?limit=20&lastKey=&search=&taxId=&customerName=&status=&startDate=&endDate=","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas"],"query":[{"key":"limit","value":"20","description":"Itens por página (default 20) - optional","disabled":false},{"key":"lastKey","value":"","description":"Cursor da próxima página, de pagination.lastKey - optional","disabled":false},{"key":"search","value":"","description":"Busca parcial por nome do tomador ou documento - optional","disabled":false},{"key":"taxId","value":"","description":"CPF/CNPJ exato do tomador, apenas dígitos - optional","disabled":false},{"key":"customerName","value":"","description":"Nome do tomador - optional","disabled":false},{"key":"status","value":"","description":"AUTHORIZED (ou ISSUED), PROCESSING, ERROR (ou FAILED), CANCELED ou REPLACED - optional","disabled":false},{"key":"startDate","value":"","description":"Data inicial da emissão, ISO 8601 - optional","disabled":false},{"key":"endDate","value":"","description":"Data final da emissão, ISO 8601 - optional","disabled":false}]},"description":"@scopes nota.fiscal/read\n\n@top\n\nLista as notas fiscais da conta, da mais recente para a mais antiga.\n\nInclui todas as origens: notas geradas por cobranças e assinaturas e também as avulsas, emitidas por POST nesta mesma rota.\n\n### O identificador da nota\n\nO campo `invoiceId` é o identificador usado nas demais rotas — consultar, cancelar, reemitir, reenviar e emitir. Na nota avulsa ele é o `ref` que você informou na emissão; nas notas geradas por cobrança, é o identificador da própria cobrança.\n\nNão o confunda com o `ref` da resposta, que traz o identificador interno da nota e serve apenas para suporte.\n\n### Status\n\n- `PROCESSING` — enviada, a prefeitura ainda não respondeu\n- `ISSUED` ou `AUTHORIZED` — autorizada. Os dois valores são equivalentes: o primeiro vem da emissão síncrona, o segundo da confirmação assíncrona da prefeitura\n- `FAILED` ou `ERROR` — recusada. `nf.errors` traz as mensagens da prefeitura\n- `CANCELED` — cancelada\n- `REPLACED` — substituída por uma reemissão\n\nNo filtro `status` os pares são intercambiáveis: `AUTHORIZED` traz também as `ISSUED`, e `ERROR` traz também as `FAILED`.\n\n### Paginação\n\nPor cursor: envie em `lastKey` o valor devolvido em `pagination.lastKey`. Enquanto `pagination.hasMore` for `true`, ainda há páginas.\n\n`emissor` identifica de qual empresa a nota saiu, útil quando a conta tem mais de uma configuração fiscal. `feeAmount` e `feeStatus` descrevem a taxa de emissão cobrada pela ValidaPay, não um tributo da nota.\n\nCase de uso:\n\n_Como plataforma, quero conciliar as notas do mês e conferir quais foram autorizadas antes de fechar o faturamento._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"items\": [\n    {\n      \"emissor\": {\n        \"configId\": \"unc_1788193720141_65g0zh12p\",\n        \"cnpj\": \"99988877000108\",\n        \"nome\": \"EMPRESA EXEMPLO LTDA\"\n      },\n      \"type\": \"NFSE\",\n      \"invoiceId\": \"nf_1788101026585_uqaspo7bn\",\n      \"chargeId\": null,\n      \"customerId\": null,\n      \"customerName\": \"Alexandre Souza\",\n      \"taxId\": \"11144477735\",\n      \"amount\": 150.00,\n      \"emitidaEm\": \"2026-08-30T14:43:49.719Z\",\n      \"ref\": \"2109541\",\n      \"status\": \"AUTHORIZED\",\n      \"feeStatus\": \"COMPLETED\",\n      \"feeAmount\": 0.37,\n      \"nf\": {\n        \"id\": \"2109541\",\n        \"number\": \"7814\",\n        \"status\": \"AUTHORIZED\",\n        \"url\": \"https://…\",\n        \"pdfUrl\": \"https://…\",\n        \"xmlPath\": \"/arquivos/…-nfse.xml\",\n        \"xmlUrl\": \"https://…\",\n        \"verificationCode\": \"PGRW-2TFA\",\n        \"rpsNumber\": \"5053\",\n        \"rpsSeries\": \"1\",\n        \"cnpj\": \"99988877000108\",\n        \"issuedAt\": \"2026-08-30T14:43:49.719Z\",\n        \"errors\": null\n      }\n    }\n  ],\n  \"pagination\": {\n    \"total\": 1,\n    \"totalPages\": 1,\n    \"limit\": 20,\n    \"hasMore\": false,\n    \"lastKey\": null\n  }\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Conta não encontrada\",\n        \"code\": \"ACCOUNT_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Resumo de Notas Fiscais","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas/summary?startDate=&endDate=","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas","summary"],"query":[{"key":"startDate","value":"","description":"Data inicial da emissão, ISO 8601 - optional","disabled":false},{"key":"endDate","value":"","description":"Data final da emissão, ISO 8601 - optional","disabled":false}]},"description":"@scopes nota.fiscal/read\n\n@top\n\nTotais de notas da conta por status, em quantidade e em valor.\n\nSem `startDate` e `endDate`, o resumo cobre todas as notas da conta.\n\nOs pares de status são somados juntos: `authorized` inclui as notas `ISSUED` e `AUTHORIZED`, e `error` inclui as `FAILED` e `ERROR`.\n\nCase de uso:\n\n_Como plataforma, quero mostrar no painel quantas notas foram autorizadas e quantas falharam no mês, sem paginar a listagem inteira._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"authorizedCount\": 128,\n  \"authorizedAmount\": 45320.75,\n  \"canceledCount\": 3,\n  \"canceledAmount\": 890.00,\n  \"errorCount\": 2,\n  \"errorAmount\": 450.00,\n  \"processingCount\": 1,\n  \"processingAmount\": 150.00,\n  \"replacedCount\": 2,\n  \"replacedAmount\": 300.00\n}","cookie":[]}]},{"name":"Consultar Nota Fiscal","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas/{{notaId}}","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas","{{notaId}}"]},"description":"@scopes nota.fiscal/read\n\n@top\n\nRetorna uma nota pelo `invoiceId` devolvido na listagem — que na nota avulsa é o `ref` informado na emissão, e na nota de cobrança é o identificador da cobrança.\n\nTraz os links do PDF e do XML e o código de verificação quando a nota já está autorizada. Quando a prefeitura recusou, `nf.errors` traz as mensagens do que precisa ser corrigido.\n\nNota inexistente, excluída ou de outra conta responde 404 com `NOTA_NOT_FOUND`.\n\nCase de uso:\n\n_Como plataforma, quero buscar o PDF de uma nota para anexar ao e-mail que envio ao meu cliente._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"emissor\": {\n    \"configId\": \"unc_1788193720141_65g0zh12p\",\n    \"cnpj\": \"99988877000108\",\n    \"nome\": \"EMPRESA EXEMPLO LTDA\"\n  },\n  \"type\": \"NFSE\",\n  \"invoiceId\": \"nf_1788101026585_uqaspo7bn\",\n  \"chargeId\": null,\n  \"customerId\": null,\n  \"customerName\": \"Alexandre Souza\",\n  \"taxId\": \"11144477735\",\n  \"amount\": 150.00,\n  \"emitidaEm\": \"2026-08-30T14:43:49.719Z\",\n  \"ref\": \"2109541\",\n  \"status\": \"ERROR\",\n  \"feeStatus\": null,\n  \"feeAmount\": null,\n  \"nf\": {\n    \"id\": \"2109541\",\n    \"number\": null,\n    \"status\": \"ERROR\",\n    \"url\": null,\n    \"pdfUrl\": null,\n    \"xmlPath\": null,\n    \"xmlUrl\": null,\n    \"verificationCode\": null,\n    \"rpsNumber\": null,\n    \"rpsSeries\": null,\n    \"cnpj\": \"99988877000108\",\n    \"issuedAt\": null,\n    \"errors\": [\n      {\n        \"mensagem\": \"Código de tributação nacional do ISS inválido para o município\"\n      }\n    ]\n  }\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Nota fiscal não encontrada\",\n        \"code\": \"NOTA_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Emitir Nota Fiscal","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas"]},"description":"@scopes nota.fiscal/write\n\n@top\n\nEmite uma nota fiscal de serviço avulsa, sem vínculo com cobrança ou assinatura.\n\nA emissão é imediata: o `invoiceTiming` da configuração fiscal vale apenas para as notas geradas a partir de cobranças, não para a avulsa.\n\nInforme em `configId` qual configuração fiscal usar — uma conta pode ter configurações de mais de uma empresa, e a nota sai no CNPJ da configuração escolhida. Liste as disponíveis em `GET /v1/invoices/notas/config`.\n\nO `ref` que você enviar passa a ser o identificador da nota nas demais rotas: consultar, cancelar, reemitir e reenviar. Omitido, a API gera um identificador próprio e o devolve na resposta.\n\nO campo `type` indica o modelo do documento fiscal. O único valor aceito hoje é `NFSE` (nota fiscal de serviço), que também é o assumido quando o campo é omitido — qualquer outro valor retorna 400 com o código `NOTA_TYPE_NOT_SUPPORTED`.\n\nOutros tipos de nota estarão disponíveis em breve. Envie `type` explicitamente desde já: quando cada modelo for liberado, nenhuma alteração no payload será necessária.\n\nO tomador não precisa estar cadastrado. Se o endereço não trouxer `cityCode`, o código IBGE do município é resolvido a partir do CEP — assim como logradouro e bairro, quando faltarem.\n\nA resposta volta com status `PROCESSING`: a prefeitura responde de forma assíncrona. Não há evento de webhook para nota fiscal — acompanhe o desfecho em `GET /v1/invoices/notas/{notaId}`, que passa a `AUTHORIZED` ou a `ERROR` com as mensagens da prefeitura.\n\nCase de uso:\n\n_Como prestador, quero emitir uma nota para um serviço cobrado fora da plataforma, informando apenas o tomador, o valor e a descrição._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `configId` | sim | Configuração fiscal, de GET /v1/invoices/notas/config |\n| `type` | não | Modelo do documento fiscal; único valor aceito hoje, outros tipos em breve. Padrão: NFSE |\n| `amount` | sim | Valor do serviço em reais |\n| `descricao` | sim | Discriminação do serviço na nota |\n| `ref` | não | Vira o identificador da nota nas demais rotas; se omitida, a API gera uma |\n| `customer` | sim |  |\n| `customer.document` | sim | CPF (11) ou CNPJ (14), apenas dígitos |\n| `customer.name` | sim | Nome completo ou razão social do tomador |\n| `customer.email` | não |  |\n| `customer.phone` | não |  |\n| `customer.address` | sim |  |\n| `customer.address.zipCode` | sim | 8 dígitos, apenas números |\n| `customer.address.street` | sim |  |\n| `customer.address.number` | sim |  |\n| `customer.address.complement` | não |  |\n| `customer.address.neighborhood` | sim |  |\n| `customer.address.city` | sim |  |\n| `customer.address.state` | sim | UF com 2 letras |\n| `customer.address.cityCode` | não | Código IBGE; resolvido pelo CEP quando ausente |","body":{"mode":"raw","raw":"{\n  \"configId\": \"unc_1776888897617_ppwgo7oef\",\n  \"type\": \"NFSE\",\n  \"amount\": 150.00,\n  \"descricao\": \"Consultoria em tecnologia da informação\",\n  \"ref\": \"pedido-2026-0912\",\n  \"customer\": {\n    \"document\": \"11144477735\",\n    \"name\": \"Alexandre Souza\",\n    \"email\": \"alexandre@exemplo.com.br\",\n    \"phone\": \"5511987654321\",\n    \"address\": {\n      \"zipCode\": \"01310100\",\n      \"street\": \"Avenida Paulista\",\n      \"number\": \"1000\",\n      \"complement\": \"Sala 5\",\n      \"neighborhood\": \"Bela Vista\",\n      \"city\": \"São Paulo\",\n      \"state\": \"SP\",\n      \"cityCode\": \"3550308\"\n    }\n  }\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"status\": \"PROCESSING\",\n  \"ref\": \"nf_1788101026585_uqaspo7bn\",\n  \"id\": \"nf_1788101026585_uqaspo7bn\",\n  \"nfStatus\": \"processando_autorizacao\",\n  \"tipo\": \"nacional\",\n  \"issuedAt\": \"2026-08-30T14:43:49.719Z\",\n  \"internalStatus\": \"PROCESSING\"\n}","cookie":[]},{"name":"400 - campos obrigatórios","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"customer.document, amount, descricao e configId são obrigatórios\",\n        \"code\": \"MISSING_FIELDS\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]},{"name":"400 - configuração inválida","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Configuração não encontrada ou desabilitada\",\n        \"code\": \"NOTA_CONFIG_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Emitir Nota de uma Cobrança","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n  \"configId\": \"unc_1776888897617_ppwgo7oef\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas/{{notaId}}/emitir","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas","{{notaId}}","emitir"]},"description":"@scopes nota.fiscal/write\n\n@top\n\nEmite a nota de uma cobrança que já existe — a que nunca emitiu e também a que falhou. O identificador na URL é o da cobrança: `invoiceId` de uma fatura de assinatura ou `chargeId` de uma cobrança avulsa.\n\nDiferente da emissão avulsa, a nota nasce ligada à cobrança: herda cliente, valor e, quando existe, assinatura e ciclo.\n\n### De onde vem a configuração fiscal\n\nNa ordem: o `configId` do corpo, depois o da nota anterior, o `nfConfigId` da cobrança e o da assinatura. Não achando nenhum, a resposta é `NF_CONFIG_REQUIRED` e nada é emitido.\n\n### Quando a emissão é recusada\n\n- `INVOICE_NOT_FOUND` (404) — cobrança inexistente ou de outra conta\n- `INVOICE_STATUS_NOT_EMITTABLE` — só emite cobrança pendente, aguardando pagamento ou paga\n- `NOTA_ALREADY_ISSUED` — já existe nota autorizada, vinculada ou agendada para essa cobrança\n- `NOTA_PROCESSING` — há uma emissão em andamento aguardando o retorno da prefeitura\n- `NF_INCOMPLETE_DATA` — faltam dados do tomador; `details` lista exatamente o que falta\n- `NF_CONFIG_NOT_FOUND` — a configuração informada não existe ou está desabilitada\n\nPara conferir os dados antes sem emitir nada, use `POST /v1/invoices/notas/{notaId}/verificar-emissao`.\n\nCase de uso:\n\n_Como prestador, quero emitir a nota de uma cobrança que ficou sem nota, sem precisar refazer a cobrança._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `configId` | não | Configuração fiscal a usar; sem ela vale a da cobrança ou da assinatura |"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"invoiceId\": \"inv_1788101026585_uqaspo7bn\",\n  \"subscriptionId\": \"sub_1788101026585_a1b2c3d4e\",\n  \"cycleNumber\": 3,\n  \"type\": \"NFSE\",\n  \"status\": \"PROCESSING\",\n  \"numero\": null,\n  \"tipo\": \"nacional\"\n}","cookie":[]},{"name":"400 - dados incompletos","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Dados incompletos para emitir a nota fiscal: CEP do cliente, Município do cliente (código IBGE)\",\n        \"code\": \"NF_INCOMPLETE_DATA\",\n        \"details\": [\n            \"CEP do cliente\",\n            \"Município do cliente (código IBGE)\"\n        ],\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]},{"name":"400 - sem emissor","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Informe o emissor (configId) para emitir a nota fiscal\",\n        \"code\": \"NF_CONFIG_REQUIRED\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Cobrança não encontrada\",\n        \"code\": \"INVOICE_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Verificar Dados para Emissão","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n  \"configId\": \"unc_1776888897617_ppwgo7oef\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas/{{notaId}}/verificar-emissao","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas","{{notaId}}","verificar-emissao"]},"description":"@scopes nota.fiscal/write\n\n@top\n\nConfere se uma cobrança tem tudo o que a nota fiscal exige, sem emitir nada. O identificador na URL é o da cobrança, como em `POST /v1/invoices/notas/{notaId}/emitir`.\n\n`ready` diz se a emissão passaria agora; `pendencias` lista em português o que falta — CPF ou CNPJ, nome, valor, endereço, CEP, município (código IBGE), logradouro ou bairro do cliente.\n\n`configId` traz a configuração fiscal que seria usada, ou `null` quando nenhuma foi encontrada. Diferente da emissão, aqui a ausência de configuração não é erro.\n\nA conferência é uma rota própria em vez de um parâmetro na rota de emissão: um flag ignorado por engano emitiria a nota de verdade.\n\nCase de uso:\n\n_Como plataforma, quero avisar o usuário sobre o cadastro incompleto do cliente antes de tentar emitir a nota e receber a recusa._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `configId` | não | Configuração fiscal a conferir; sem ela vale a da cobrança ou da assinatura |"},"response":[{"name":"200 - pronta para emitir","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"invoiceId\": \"inv_1788101026585_uqaspo7bn\",\n  \"ready\": true,\n  \"pendencias\": [],\n  \"configId\": \"unc_1788193720141_65g0zh12p\",\n  \"amount\": 150.00\n}","cookie":[]},{"name":"200 - com pendências","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"invoiceId\": \"inv_1788101026585_uqaspo7bn\",\n  \"ready\": false,\n  \"pendencias\": [\n    \"CEP do cliente\",\n    \"Município do cliente (código IBGE)\"\n  ],\n  \"configId\": \"unc_1788193720141_65g0zh12p\",\n  \"amount\": 150.00\n}","cookie":[]}]},{"name":"Cancelar Nota Fiscal","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"DELETE","header":[],"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas/{{notaId}}?motivo=Valor do servico informado incorretamente","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas","{{notaId}}"],"query":[{"key":"motivo","value":"Valor do servico informado incorretamente","description":"Justificativa enviada à prefeitura - required","disabled":false}]},"description":"@scopes nota.fiscal/write\n\n@top\n\nCancela na prefeitura uma nota fiscal já autorizada. O identificador é o `invoiceId` da listagem.\n\nO motivo vai na query string, e não no corpo: parte dos clientes HTTP descarta body em requisições DELETE.\n\nSó é possível cancelar notas da própria conta e que estejam autorizadas. O status é reconferido antes do cancelamento: nota em processamento ou já cancelada é recusada com `NF_NOT_AUTHORIZED`.\n\nO prazo de cancelamento é definido pela prefeitura do município emissor. Passada essa janela, o cancelamento é recusado com `NF_CANCEL_FAILED` e a correção passa a exigir substituição da nota.\n\nCase de uso:\n\n_Como prestador, quero cancelar uma nota emitida com valor errado, dentro do prazo permitido pelo município._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"invoiceId\": \"nf_1788101026585_uqaspo7bn\"\n}","cookie":[]},{"name":"400 - não autorizada","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Nota fiscal não está autorizada para cancelamento\",\n        \"code\": \"NF_NOT_AUTHORIZED\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Nota fiscal não encontrada\",\n        \"code\": \"NOTA_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Reemitir Nota Fiscal","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas/{{notaId}}/reemitir","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas","{{notaId}}","reemitir"]},"description":"@scopes nota.fiscal/write\n\n@top\n\nGera uma nova nota para uma emissão que falhou na prefeitura. O identificador é o `invoiceId` da listagem.\n\nSó vale para notas que não foram autorizadas: uma nota já autorizada é recusada com `NOTA_ALREADY_ISSUED` — nesse caso o caminho é cancelar e emitir de novo.\n\nA nota anterior fica com status `REPLACED` e a nova assume o lugar dela. A configuração fiscal usada é a mesma da nota anterior.\n\nCorrija a causa da recusa antes de reemitir: a mensagem da prefeitura está em `nf.errors`, na consulta da nota.\n\nCase de uso:\n\n_Como prestador, quero reprocessar uma nota recusada por erro de cadastro, depois de corrigir a configuração fiscal._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"invoiceId\": \"nf_1788101026585_uqaspo7bn\",\n  \"subscriptionId\": null,\n  \"cycleNumber\": null,\n  \"type\": \"NFSE\",\n  \"status\": \"PROCESSING\",\n  \"numero\": null,\n  \"tipo\": \"nacional\"\n}","cookie":[]},{"name":"400 - já autorizada","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Nota já autorizada — não pode ser reemitida\",\n        \"code\": \"NOTA_ALREADY_ISSUED\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Reenviar Nota por E-mail","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas/{{notaId}}/reenviar","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas","{{notaId}}","reenviar"]},"description":"@scopes nota.fiscal/write\n\n@top\n\nReenvia por e-mail uma nota já autorizada. O identificador é o `invoiceId` da listagem.\n\nAceita até 10 destinatários por chamada — acima disso a resposta é `TOO_MANY_EMAILS`. Notas que ainda não foram autorizadas são recusadas com `NOTA_NOT_ISSUED`.\n\nA nota segue anexada em PDF e XML.\n\nCase de uso:\n\n_Como prestador, quero reenviar a nota para um segundo e-mail do cliente, sem precisar baixar e anexar o PDF manualmente._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `emails` | sim | No máximo 10 destinatários |","body":{"mode":"raw","raw":"{\n  \"emails\": [\n    \"financeiro@exemplo.com.br\",\n    \"contabilidade@exemplo.com.br\"\n  ]\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true,\n  \"emails\": [\n    \"financeiro@exemplo.com.br\",\n    \"contabilidade@exemplo.com.br\"\n  ]\n}","cookie":[]},{"name":"400 - sem e-mail","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Informe ao menos um e-mail\",\n        \"code\": \"EMAILS_REQUIRED\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Listar Configurações Fiscais","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas/config","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas","config"]},"description":"@scopes nota.fiscal/read\n\n@top\n\nLista as configurações fiscais da conta.\n\nUse o `id` de cada uma como `configId` ao emitir uma nota avulsa, e como `nfConfigId` em cobranças, produtos e assinaturas.\n\nA resposta traz também `defaults`: os valores que a API preencheria sozinha a partir do cadastro da conta — CNPJ, endereço, contato e código IBGE do município — úteis para montar a tela de cadastro já preenchida.\n\nSegredos nunca são devolvidos. De `prefeitura` vêm o `login`, `has_senha` e a numeração do RPS; do certificado, se existe e a validade.\n\nCase de uso:\n\n_Como plataforma, quero listar as empresas emissoras da conta para escolher por qual emitir cada nota._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"configs\": [\n    {\n      \"id\": \"unc_1788193720141_65g0zh12p\",\n      \"accountId\": \"460851686\",\n      \"config_name\": \"Matriz\",\n      \"enabled\": true,\n      \"invoiceTiming\": \"IMMEDIATE\",\n      \"codigo_tributacao_nacional_iss\": \"010701\",\n      \"tributacao_iss\": 1,\n      \"tipo_retencao_iss\": 1,\n      \"serie_dps\": \"1\",\n      \"prestador\": {\n        \"cnpj\": \"99988877000108\",\n        \"nome_fantasia\": \"EMPRESA EXEMPLO LTDA\",\n        \"inscricao_municipal\": \"1234567\",\n        \"codigo_municipio\": \"4205407\",\n        \"codigo_municipio_prestacao\": \"4205407\",\n        \"codigo_opcao_simples_nacional\": 1,\n        \"regime_especial_tributacao\": 0\n      },\n      \"prefeitura\": {\n        \"login\": \"usuario-do-portal\",\n        \"has_senha\": true,\n        \"serie_rps\": \"1\",\n        \"proximo_numero_rps\": 145\n      },\n      \"certificate\": {\n        \"has_certificate\": true,\n        \"expiry_date\": \"2026-11-18T11:01:15.000Z\"\n      },\n      \"createdAt\": \"2026-08-31T16:28:43.167Z\",\n      \"updatedAt\": \"2026-08-31T16:28:43.167Z\"\n    }\n  ],\n  \"defaults\": {\n    \"prestador\": {\n      \"cnpj\": \"99988877000108\",\n      \"nome_fantasia\": \"EMPRESA EXEMPLO LTDA\",\n      \"email\": \"fiscal@exemplo.com.br\",\n      \"telefone\": \"5548999999999\",\n      \"codigo_municipio\": \"4205407\",\n      \"codigo_municipio_prestacao\": \"4205407\",\n      \"endereco\": {\n        \"logradouro\": \"RUA DAS PALMEIRAS\",\n        \"numero\": \"110\",\n        \"bairro\": \"CENTRO\",\n        \"cep\": \"88010000\",\n        \"uf\": \"SC\"\n      }\n    },\n    \"responsavel\": {\n      \"nome\": \"Maria Souza\",\n      \"cpf\": \"11144477735\"\n    }\n  }\n}","cookie":[]}]},{"name":"Consultar Configuração Fiscal","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"GET","header":[],"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas/config/{{configId}}","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas","config","{{configId}}"]},"description":"@scopes nota.fiscal/read\n\n@top\n\nRetorna uma configuração fiscal pelo `id`.\n\nSegredos nunca são devolvidos: a senha do certificado e a senha da prefeitura ficam de fora. `certificate.expiry_date` traz o vencimento do certificado, e `prefeitura.has_senha` diz se há credencial gravada.\n\nConfiguração inexistente ou de outra conta responde `{}`, e não 404.\n\nCase de uso:\n\n_Como plataforma, quero conferir a validade do certificado de uma empresa antes que ela pare de emitir._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"unc_1788193720141_65g0zh12p\",\n  \"accountId\": \"460851686\",\n  \"config_name\": \"Matriz\",\n  \"enabled\": true,\n  \"invoiceTiming\": \"IMMEDIATE\",\n  \"codigo_tributacao_nacional_iss\": \"010701\",\n  \"tributacao_iss\": 1,\n  \"tipo_retencao_iss\": 1,\n  \"serie_dps\": \"1\",\n  \"descricao_servico\": \"Prestação de Serviços\",\n  \"prestador\": {\n    \"cnpj\": \"99988877000108\",\n    \"nome_fantasia\": \"EMPRESA EXEMPLO LTDA\",\n    \"inscricao_municipal\": \"1234567\",\n    \"codigo_municipio\": \"4205407\",\n    \"codigo_municipio_prestacao\": \"4205407\",\n    \"codigo_opcao_simples_nacional\": 1,\n    \"regime_especial_tributacao\": 0\n  },\n  \"prefeitura\": {\n    \"login\": \"usuario-do-portal\",\n    \"has_senha\": true,\n    \"serie_rps\": \"1\",\n    \"proximo_numero_rps\": 145\n  },\n  \"certificate\": {\n    \"has_certificate\": true,\n    \"expiry_date\": \"2026-11-18T11:01:15.000Z\"\n  },\n  \"createdAt\": \"2026-08-31T16:28:43.167Z\",\n  \"updatedAt\": \"2026-08-31T16:28:43.167Z\"\n}","cookie":[]}]},{"name":"Criar Configuração Fiscal","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"POST","header":[],"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas/config","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas","config"]},"description":"@scopes nota.fiscal/write\n\n@top\n\nCadastra a empresa emissora: CNPJ, regime tributário, certificado digital e os tributos que entram na nota.\n\nO `id` devolvido aqui é o `configId` da emissão avulsa e o `nfConfigId` de cobranças, produtos e assinaturas. Uma conta pode ter mais de uma configuração — o CNPJ do prestador define de qual empresa a nota sai.\n\nO que não for enviado é preenchido a partir do cadastro da conta: CNPJ, endereço, contato e código IBGE do município. Enviar explicitamente evita depender desses dados.\n\nA criação valida e registra a empresa emissora, incluindo o certificado. Se essa etapa falhar, nada é gravado e o certificado enviado é descartado — não sobra configuração pela metade.\n\nNão envie `id` no corpo: com ele a chamada vira atualização da configuração existente.\n\n### Municipal ou nacional: quem decide é o município\n\nO código IBGE em `prestador.codigo_municipio` determina por qual padrão a nota sai, e isso muda quais campos tributários são lidos:\n\n- **NFS-en nacional** — padrão nacional da NFS-e, adotado pela maior parte dos municípios. Usa `codigo_tributacao_nacional_iss`, `tributacao_iss`, `tipo_retencao_iss`, `serie_dps` e os campos de PIS/COFINS ou do Simples, conforme o regime.\n- **NFS-e municipal** — municípios com sistema próprio. Usa `item_lista_servico`, `aliquota_iss`, `iss_retido`, `natureza_operacao` e, quando o município exige, `codigo_cnae` e `codigo_tributario_municipio`.\n\nVocê não precisa escolher: a rota é resolvida na emissão, a partir do município do prestador. `tipo_nf` força um dos dois padrões e só faz sentido quando o município aceita ambos.\n\nNa dúvida sobre em qual padrão o seu município está, preencha os dois conjuntos — o que não se aplica é ignorado.\n\n### Credencial da prefeitura e numeração do RPS\n\nO certificado digital A1 basta na maior parte dos municípios. Os que têm sistema próprio podem exigir também uma credencial do portal, enviada em `prefeitura` — nem todos pedem `login`, e há municípios em que só a senha é necessária.\n\nConfira o portal do seu município antes de preencher. Em parte deles o que vai em `senha` é uma chave digital gerada no perfil do usuário, e não a senha de acesso ao portal — usar a senha errada só aparece como falha de autenticação na primeira emissão.\n\n### Numeração\n\nCada padrão tem a sua, e as duas continuam a sequência que a prefeitura já registrou para a empresa — em branco, a numeração começa do início.\n\n- **NFS-e municipal** — `prefeitura.serie_rps` e `prefeitura.proximo_numero_rps`.\n- **NFS-en nacional** — `serie_dps`, no primeiro nível do corpo. A série declarada no cadastro é a mesma que vai em cada emissão e precisa bater com a registrada na prefeitura; a sequência dos números é mantida pela ValidaPay.\n\n### Quando a nota é emitida\n\n`invoiceTiming` define o momento da emissão das notas geradas por cobrança:\n\n- `IMMEDIATE` — junto com a cobrança. É o padrão.\n- `AFTER_CONFIRMATION` — somente após a confirmação do pagamento.\n- `DAYS_AFTER_CONFIRMATION` — `daysAfterConfirmation` dias depois da confirmação (padrão 1).\n\nA emissão avulsa por `POST /v1/invoices/notas` sai sempre na hora, qualquer que seja o valor configurado.\n\n> ⚠️ **Atenção:** configurações criadas pelo painel trazem também `quando_emitir`, com os mesmos três valores. Ele é apenas o espelho gravado pela tela — quem define o agendamento é `invoiceTiming`.\n\n### Campos exigidos pelo regime\n\nO regime vem de `prestador.codigo_opcao_simples_nacional`:\n\n- **1, não optante** — exige `situacao_tributaria_pis_cofins`, `aliquota_pis` e `aliquota_cofins`.\n- **2 (MEI) e 3 (ME/EPP)** — exigem `percentual_total_tributos_simples_nacional`.\n\nFaltando um deles, a configuração não é gravada e a resposta traz a mensagem da validação com o código `INTERNAL_ERROR`.\n\nCase de uso:\n\n_Como plataforma, quero cadastrar a empresa emissora e o certificado digital por API, para habilitar a emissão de notas sem passar pelo painel._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `config_name` | não | Nome para diferenciar as configurações da conta |\n| `enabled` | não | Default true; configuração desabilitada não emite |\n| `razao_social` | não | Razão social da empresa emissora; sem ela vale o nome_fantasia |\n| `invoiceTiming` | não | Momento da emissão nas notas geradas por cobrança. Default IMMEDIATE (valores: IMMEDIATE, AFTER_CONFIRMATION, DAYS_AFTER_CONFIRMATION) |\n| `daysAfterConfirmation` | não | Dias após a confirmação, quando invoiceTiming for DAYS_AFTER_CONFIRMATION. Default 1 (mín.: 1) |\n| `tipo_nf` | não | Força o padrão de emissão; por padrão quem decide é o município do prestador (valores: municipal, nacional) |\n| `descricao_servico` | não | Discriminação padrão do serviço, usada quando a cobrança não traz o nome do item |\n| `enviar_email_destinatario` | não | Default true; a nota é enviada ao tomador por e-mail na autorização |\n| `codigo_tributacao_nacional_iss` | sim | NFS-en: código de tributação nacional do ISS, 6 dígitos |\n| `tributacao_iss` | sim | NFS-en: 1 tributável, 2 imunidade, 3 exportação, 4 não incidência |\n| `tipo_retencao_iss` | sim | NFS-en: 1 não retido, 2 retido pelo tomador, 3 pelo intermediário |\n| `serie_dps` | não | NFS-en: série da DPS, declarada no cadastro e enviada em cada emissão. Default 1 |\n| `situacao_tributaria_pis_cofins` | sim | se não optante pelo Simples - NFS-en |\n| `aliquota_pis` | sim | se não optante - Percentual aplicado sobre o valor do serviço |\n| `aliquota_cofins` | sim | se não optante - Percentual aplicado sobre o valor do serviço |\n| `aliquota_csll` | não | Percentual; vira o valor de CSLL da nota |\n| `aliquota_irrf` | não | Percentual; vira o valor de IRRF da nota |\n| `tipo_retencao_pis_cofins` | não | 0 não retido |\n| `percentual_total_tributos_federais` | não | Percentual informado na nota |\n| `percentual_total_tributos_estaduais` | não | Percentual informado na nota |\n| `percentual_total_tributos_municipais` | não | Percentual informado na nota |\n| `percentual_total_tributos_simples_nacional` | sim | se optante pelo Simples (MEI ou ME/EPP) |\n| `regime_tributario_simples_nacional` | não | 1 federais e municipal pelo SN. Default 1 |\n| `item_lista_servico` | não | Obrigatório na NFS-e municipal: item da lista de serviços, formato NN.NN |\n| `aliquota_iss` | não | Obrigatório na NFS-e municipal: alíquota do ISS em percentual |\n| `iss_retido` | não | NFS-e municipal: ISS retido pelo tomador. Default false |\n| `natureza_operacao` | não | NFS-e municipal. Default 1 |\n| `codigo_cnae` | não | NFS-e municipal; exigido por parte dos municípios |\n| `codigo_tributario_municipio` | não | NFS-e municipal; exigido por parte dos municípios |\n| `prestador` | sim |  |\n| `prestador.cnpj` | sim | 14 dígitos, apenas números |\n| `prestador.inscricao_municipal` | não |  |\n| `prestador.inscricao_estadual` | não |  |\n| `prestador.nome_fantasia` | não |  |\n| `prestador.email` | não |  |\n| `prestador.telefone` | não |  |\n| `prestador.codigo_municipio` | sim | Código IBGE do município, 7 dígitos; define o padrão de emissão |\n| `prestador.codigo_municipio_prestacao` | não | Default igual a codigo_municipio |\n| `prestador.codigo_opcao_simples_nacional` | sim | NÚMERO, não string. 1 não optante, 2 MEI, 3 ME/EPP |\n| `prestador.regime_especial_tributacao` | sim | 0 nenhum |\n| `prestador.endereco` | não | Preenchido pelo cadastro da conta quando ausente |\n| `prestador.endereco.logradouro` | não |  |\n| `prestador.endereco.numero` | não |  |\n| `prestador.endereco.complemento` | não |  |\n| `prestador.endereco.bairro` | não |  |\n| `prestador.endereco.municipio` | não |  |\n| `prestador.endereco.cep` | não |  |\n| `prestador.endereco.uf` | não |  |\n| `prefeitura` | não | Credencial do portal e numeração do RPS, na NFS-e municipal |\n| `prefeitura.login` | não | Só nos municípios que pedem login |\n| `prefeitura.senha` | não | Em parte dos municípios é a chave digital, não a senha de acesso |\n| `prefeitura.serie_rps` | não | Série do RPS registrada na prefeitura |\n| `prefeitura.proximo_numero_rps` | não | Número do próximo RPS a emitir (mín.: 1) |\n| `responsavel` | não | Guardado no cadastro; não vai para a nota |\n| `responsavel.nome` | não |  |\n| `responsavel.cpf` | não |  |\n| `certificate` | não | Sem certificado a prefeitura normalmente recusa a empresa |\n| `certificate.pfx_base64` | sim | Certificado A1 em base64; anda junto com password |\n| `certificate.password` | sim |  |","body":{"mode":"raw","raw":"{\n  \"config_name\": \"Matriz\",\n  \"enabled\": true,\n  \"razao_social\": \"EMPRESA EXEMPLO LTDA\",\n  \"invoiceTiming\": \"IMMEDIATE\",\n  \"daysAfterConfirmation\": 1,\n  \"tipo_nf\": \"nacional\",\n  \"descricao_servico\": \"Prestação de Serviços\",\n  \"enviar_email_destinatario\": true,\n\n  \"codigo_tributacao_nacional_iss\": \"010701\",\n  \"tributacao_iss\": 1,\n  \"tipo_retencao_iss\": 1,\n  \"serie_dps\": \"1\",\n\n  \"situacao_tributaria_pis_cofins\": \"01\",\n  \"aliquota_pis\": 0.65,\n  \"aliquota_cofins\": 3,\n  \"aliquota_csll\": 0,\n  \"aliquota_irrf\": 0,\n  \"tipo_retencao_pis_cofins\": 0,\n  \"percentual_total_tributos_federais\": 5.65,\n  \"percentual_total_tributos_estaduais\": 0,\n  \"percentual_total_tributos_municipais\": 2,\n  \"percentual_total_tributos_simples_nacional\": 6,\n  \"regime_tributario_simples_nacional\": 1,\n\n  \"item_lista_servico\": \"07.02\",\n  \"aliquota_iss\": 2,\n  \"iss_retido\": false,\n  \"natureza_operacao\": \"1\",\n  \"codigo_cnae\": \"6201500\",\n  \"codigo_tributario_municipio\": \"620150001\",\n\n  \"prestador\": {\n    \"cnpj\": \"99988877000108\",\n    \"inscricao_municipal\": \"1234567\",\n    \"inscricao_estadual\": \"\",\n    \"nome_fantasia\": \"EMPRESA EXEMPLO LTDA\",\n    \"email\": \"fiscal@exemplo.com.br\",\n    \"telefone\": \"5548999999999\",\n    \"codigo_municipio\": \"4205407\",\n    \"codigo_municipio_prestacao\": \"4205407\",\n    \"codigo_opcao_simples_nacional\": 1,\n    \"regime_especial_tributacao\": 0,\n    \"endereco\": {\n      \"logradouro\": \"RUA DAS PALMEIRAS\",\n      \"numero\": \"110\",\n      \"complemento\": \"\",\n      \"bairro\": \"CENTRO\",\n      \"municipio\": \"Florianópolis\",\n      \"cep\": \"88010000\",\n      \"uf\": \"SC\"\n    }\n  },\n\n  \"prefeitura\": {\n    \"login\": \"usuario-do-portal\",\n    \"senha\": \"chave-ou-senha-do-portal\",\n    \"serie_rps\": \"1\",\n    \"proximo_numero_rps\": 1\n  },\n\n  \"responsavel\": {\n    \"nome\": \"Maria Souza\",\n    \"cpf\": \"11144477735\"\n  },\n\n  \"certificate\": {\n    \"pfx_base64\": \"MIIQ…\",\n    \"password\": \"senha-do-certificado\"\n  }\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"201","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"unc_1788193720141_65g0zh12p\",\n  \"accountId\": \"460851686\",\n  \"config_name\": \"Matriz\",\n  \"enabled\": true,\n  \"invoiceTiming\": \"IMMEDIATE\",\n  \"codigo_tributacao_nacional_iss\": \"010701\",\n  \"tributacao_iss\": 1,\n  \"tipo_retencao_iss\": 1,\n  \"serie_dps\": \"1\",\n  \"descricao_servico\": \"Prestação de Serviços\",\n  \"prestador\": {\n    \"cnpj\": \"99988877000108\",\n    \"nome_fantasia\": \"EMPRESA EXEMPLO LTDA\",\n    \"inscricao_municipal\": \"1234567\",\n    \"codigo_municipio\": \"4205407\",\n    \"codigo_municipio_prestacao\": \"4205407\",\n    \"codigo_opcao_simples_nacional\": 1,\n    \"regime_especial_tributacao\": 0\n  },\n  \"prefeitura\": {\n    \"login\": \"usuario-do-portal\",\n    \"has_senha\": true,\n    \"serie_rps\": \"1\",\n    \"proximo_numero_rps\": 145\n  },\n  \"certificate\": {\n    \"has_certificate\": true,\n    \"expiry_date\": \"2026-11-18T11:01:15.000Z\"\n  },\n  \"createdAt\": \"2026-08-31T16:28:43.167Z\",\n  \"updatedAt\": \"2026-08-31T16:28:43.167Z\"\n}","cookie":[]},{"name":"400 - sincronização","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Mensagem devolvida pela prefeitura\",\n        \"code\": \"NF_CONFIG_SYNC_FAILED\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]},{"name":"500 - regime incompleto","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"aliquota_pis é obrigatório para regime Não Optante\",\n        \"code\": \"INTERNAL_ERROR\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Atualizar Configuração Fiscal","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"PUT","header":[],"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas/config/{{configId}}","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas","config","{{configId}}"]},"description":"@scopes nota.fiscal/write\n\n@top\n\nAtualiza uma configuração fiscal. Envie apenas os campos que mudam — os demais são preservados.\n\n> ⚠️ **Atenção:** o merge é por campo do primeiro nível, não por campo aninhado. Enviar `prestador` com dois campos substitui o objeto `prestador` inteiro, apagando o que não veio. O mesmo vale para `endereco` e `certificate`: monte o objeto completo antes de enviar.\n\n`prefeitura` é a exceção: os campos enviados são mesclados com os já gravados, então dá para alterar só a série do RPS sem reenviar a senha.\n\nEnviar `null` em um campo o remove da configuração.\n\n`certificate` com `pfx_base64` e `password` substitui o certificado e revalida a empresa emissora; o certificado anterior é apagado, a menos que outra configuração da conta use o mesmo arquivo.\n\nQualquer alteração revalida a empresa emissora. Se essa etapa falhar, nada é gravado.\n\nCase de uso:\n\n_Como plataforma, quero trocar o certificado digital antes do vencimento, sem recriar a configuração._\n\n#### Campos do body\n\n| Campo | Obrigatório | Descrição |\n|---|---|---|\n| `config_name` | não |  |\n| `enabled` | não | false desliga a emissão sem apagar a configuração |\n| `invoiceTiming` | não | Momento da emissão nas notas geradas por cobrança (valores: IMMEDIATE, AFTER_CONFIRMATION, DAYS_AFTER_CONFIRMATION) |\n| `daysAfterConfirmation` | não | Só com invoiceTiming DAYS_AFTER_CONFIRMATION (mín.: 1) |\n| `descricao_servico` | não |  |\n| `codigo_tributacao_nacional_iss` | não |  |\n| `tributacao_iss` | não |  |\n| `tipo_retencao_iss` | não |  |\n| `aliquota_iss` | não | NFS-e municipal |\n| `item_lista_servico` | não | NFS-e municipal |\n| `serie_dps` | não | NFS-en: série da DPS |\n| `prefeitura` | não | Mesclado com o que já está gravado; envie só o que muda |\n| `prefeitura.login` | não |  |\n| `prefeitura.senha` | não | Só quando a credencial muda |\n| `prefeitura.serie_rps` | não | Série do RPS registrada na prefeitura |\n| `prefeitura.proximo_numero_rps` | não | Número do próximo RPS a emitir (mín.: 1) |\n| `certificate` | não | Só para substituir o certificado |\n| `certificate.pfx_base64` | sim |  |\n| `certificate.password` | sim |  |","body":{"mode":"raw","raw":"{\n  \"config_name\": \"Matriz\",\n  \"enabled\": true,\n  \"invoiceTiming\": \"AFTER_CONFIRMATION\",\n  \"daysAfterConfirmation\": 3,\n  \"descricao_servico\": \"Consultoria em tecnologia da informação\",\n  \"codigo_tributacao_nacional_iss\": \"010701\",\n  \"tributacao_iss\": 1,\n  \"tipo_retencao_iss\": 1,\n  \"aliquota_iss\": 2,\n  \"item_lista_servico\": \"07.02\",\n  \"serie_dps\": \"1\",\n  \"prefeitura\": {\n    \"login\": \"usuario-do-portal\",\n    \"senha\": \"chave-ou-senha-do-portal\",\n    \"serie_rps\": \"1\",\n    \"proximo_numero_rps\": 145\n  },\n  \"certificate\": {\n    \"pfx_base64\": \"MIIQ…\",\n    \"password\": \"senha-do-certificado\"\n  }\n}","options":{"raw":{"language":"json"}}}},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"id\": \"unc_1788193720141_65g0zh12p\",\n  \"accountId\": \"460851686\",\n  \"config_name\": \"Matriz\",\n  \"enabled\": true,\n  \"invoiceTiming\": \"IMMEDIATE\",\n  \"codigo_tributacao_nacional_iss\": \"010701\",\n  \"tributacao_iss\": 1,\n  \"tipo_retencao_iss\": 1,\n  \"serie_dps\": \"1\",\n  \"descricao_servico\": \"Prestação de Serviços\",\n  \"prestador\": {\n    \"cnpj\": \"99988877000108\",\n    \"nome_fantasia\": \"EMPRESA EXEMPLO LTDA\",\n    \"inscricao_municipal\": \"1234567\",\n    \"codigo_municipio\": \"4205407\",\n    \"codigo_municipio_prestacao\": \"4205407\",\n    \"codigo_opcao_simples_nacional\": 1,\n    \"regime_especial_tributacao\": 0\n  },\n  \"prefeitura\": {\n    \"login\": \"usuario-do-portal\",\n    \"has_senha\": true,\n    \"serie_rps\": \"1\",\n    \"proximo_numero_rps\": 145\n  },\n  \"certificate\": {\n    \"has_certificate\": true,\n    \"expiry_date\": \"2026-11-18T11:01:15.000Z\"\n  },\n  \"createdAt\": \"2026-08-31T16:28:43.167Z\",\n  \"updatedAt\": \"2026-08-31T16:28:43.167Z\"\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Configuração não encontrada\",\n        \"code\": \"NOTA_CONFIG_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]},{"name":"Excluir Configuração Fiscal","request":{"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{token}}","type":"string"}]},"method":"DELETE","header":[],"url":{"raw":"https://api.validapay.com.br/v1/invoices/notas/config/{{configId}}","protocol":"https","host":["api","validapay","com","br"],"path":["v1","invoices","notas","config","{{configId}}"]},"description":"@scopes nota.fiscal/write\n\n@top\n\nRemove uma configuração fiscal da conta.\n\nA exclusão vale para a plataforma. As notas já emitidas por ela não são afetadas.\n\nCase de uso:\n\n_Como plataforma, quero remover a configuração de uma empresa que deixou de operar._"},"response":[{"name":"200","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n  \"success\": true\n}","cookie":[]},{"name":"404","originalRequest":{"method":"GET","header":[],"url":{"raw":""}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"body":"{\n    \"error\": {\n        \"message\": \"Configuração não encontrada\",\n        \"code\": \"NOTA_CONFIG_NOT_FOUND\",\n        \"details\": null,\n        \"timestamp\": \"2026-07-14T21:39:36.322Z\"\n    }\n}","cookie":[]}]}]}]}