{ "info": { "name": "Documentação ValidaPay2", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": "Collection completa da API ValidaPay. Rotas REST padronizadas, valores monetários em reais (BRL), auth Bearer (Cognito) ou M2M (client_credentials). Path params usam :id." }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "variable": [ { "key": "base_url", "value": "https://api.validapay.com.br" }, { "key": "token", "value": "" }, { "key": "client_id", "value": "" }, { "key": "client_secret", "value": "" }, { "key": "scope", "value": "pix.cob/read pix.cob/write wallet/read wallet/write products/read products/write proposals/read proposals/write subscriptions/read subscriptions/write checkouts/read checkouts/write customers/read customers/write subaccounts/read coupons/read coupons/write payment.methods/write" }, { "key": "subaccount_number", "value": "" } ], "item": [ { "name": "Autenticação", "item": [ { "name": "Gerar Token", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{auth_url}}" ], "path": [ "auth", "token" ], "raw": "{{auth_url}}/auth/token" }, "description": "Autentica as credenciais e retorna um token de acesso para uso nas demais rotas da API.\n\n# Autenticação M2M (client_credentials)\n\nGera um access token Bearer para chamadas M2M.\n\n**Auth:** nenhuma (credenciais no body)\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `grant_type` | ✅ | string | `client_credentials` |\n| `client_id` | ✅ | string | ID do cliente M2M |\n| `client_secret` | ✅ | string | Secret do cliente M2M |\n| `scope` | ✅ | string | Escopos separados por espaço |\n\n**Scopes disponíveis:** `pix.cob/read` `pix.cob/write` `wallet/read` `wallet/write` `products/read` `products/write` `proposals/read` `proposals/write` `subscriptions/read` `subscriptions/write` `checkouts/read` `checkouts/write` `customers/read` `customers/write` `subaccounts/read` `coupons/read` `coupons/write` `payment.methods/write`", "body": { "mode": "raw", "raw": "{\n \"grant_type\": \"client_credentials\",\n \"client_id\": \"{{client_id}}\",\n \"client_secret\": \"{{client_secret}}\",\n \"scope\": \"{{scope}}\"\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 \"access_token\": \"eyJ...\",\n \"expires_in\": 3600,\n \"token_type\": \"Bearer\"\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\": \"invalid_client\",\n \"error_description\": \"Client authentication failed\"\n}", "cookie": [] } ] } ] }, { "name": "Contas e Subcontas", "item": [ { "name": "Criar Proposta PF", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "proposals" ], "raw": "{{base_url}}/v1/proposals" }, "description": "Envia ou atualiza o formulário de abertura de conta para pessoa física, incluindo dados pessoais e documentos.\n\n# Criar/atualizar proposta (Pessoa Física)\n\n`documentNumber` com 11 dígitos determina PF. `financialDetails` é obrigatório para finalizar (`status: FINISHED`); sem ele retorna `UNFINISHED`.\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `documentNumber` | ✅ | string | CPF 11 dígitos |\n| `fullName` | ✅ | string | Nome completo |\n| `phoneNumber` | ✅ | string | E.164 |\n| `email` | ✅ | string | email válido |\n| `motherName` | ✅ | string | Nome da mãe |\n| `birthDate` | ✅ | string | YYYY-MM-DD |\n| `isPoliticallyExposedPerson` | ✅ | boolean | PEP |\n| `address.*` | ✅ | object | CEP, logradouro, número, bairro, cidade, UF |\n| `financialDetails.*` | ✅* | object | renda, profissão, patrimônio (obrig. p/ finalizar) |\n| `webhookUrl` | ❌ | string | Notificações de onboarding |", "body": { "mode": "raw", "raw": "{\n \"documentNumber\": \"12345678901\",\n \"fullName\": \"João da Silva\",\n \"phoneNumber\": \"+5511999998888\",\n \"email\": \"joao@email.com\",\n \"motherName\": \"Maria da Silva\",\n \"birthDate\": \"1990-01-15\",\n \"isPoliticallyExposedPerson\": false,\n \"socialName\": null,\n \"address\": {\n \"postalCode\": \"01310100\",\n \"street\": \"Av. Paulista\",\n \"number\": \"1000\",\n \"neighborhood\": \"Bela Vista\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"addressComplement\": \"Apto 52\"\n },\n \"financialDetails\": {\n \"declaredIncome\": \"5000.00\",\n \"occupation\": \"Desenvolvedor\",\n \"netWorth\": \"50000.00\"\n },\n \"webhookUrl\": \"https://meusite.com/webhook\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 FINISHED", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": \"FINISHED\",\n \"formId\": \"form_xxx\",\n \"sendStatus\": \"SENT\",\n \"proposalId\": \"prop_xxx\"\n}", "cookie": [] }, { "name": "200 UNFINISHED", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": \"UNFINISHED\",\n \"formId\": \"form_xxx\",\n \"pendingFields\": [\n \"financialDetails.declaredIncome\"\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 \"code\": \"INVALID_DOCUMENT\",\n \"message\": \"CPF inválido\"\n}", "cookie": [] } ] }, { "name": "Criar Proposta PJ", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "proposals" ], "raw": "{{base_url}}/v1/proposals" }, "description": "Envia ou atualiza o formulário de abertura de conta para pessoa jurídica, incluindo dados da empresa e sócios.\n\n# Criar/atualizar proposta (Pessoa Jurídica)\n\n`documentNumber` com 14 dígitos determina PJ. Exige ao menos um sócio em `owner[]`.\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `documentNumber` | ✅ | string | CNPJ 14 dígitos |\n| `businessName` | ✅ | string | Razão social |\n| `tradingName` | ✅ | string | Nome fantasia |\n| `businessEmail` | ✅ | string | email |\n| `contactNumber` | ✅ | string | E.164 |\n| `companyType` | ❌ | string | `PJ` `MEI` `ME` |\n| `businessAddress` | ✅ | object | Endereço da empresa |\n| `financialCompanyDetails.declaredCompanyRevenue` | ✅* | string | Faturamento mensal |\n| `owner[]` | ✅ | array | min 1 sócio |\n| `owner[].ownerType` | ✅ | string | `REPRESENTANTE` `SOCIO` `DEMAIS SOCIOS` |", "body": { "mode": "raw", "raw": "{\n \"documentNumber\": \"12345678000195\",\n \"businessName\": \"Empresa LTDA\",\n \"tradingName\": \"Empresa\",\n \"businessEmail\": \"contato@empresa.com\",\n \"contactNumber\": \"+5511999998888\",\n \"companyType\": \"PJ\",\n \"businessAddress\": {\n \"postalCode\": \"01310100\",\n \"street\": \"Av. Paulista\",\n \"number\": \"1000\",\n \"neighborhood\": \"Bela Vista\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"addressComplement\": null\n },\n \"financialCompanyDetails\": {\n \"declaredCompanyRevenue\": \"100000.00\"\n },\n \"owner\": [\n {\n \"ownerType\": \"REPRESENTANTE\",\n \"documentNumber\": \"12345678901\",\n \"fullName\": \"João da Silva\",\n \"phoneNumber\": \"+5511999998888\",\n \"email\": \"joao@empresa.com\",\n \"motherName\": \"Maria da Silva\",\n \"birthDate\": \"1980-05-20\",\n \"isPoliticallyExposedPerson\": false,\n \"address\": {\n \"postalCode\": \"01310100\",\n \"street\": \"Av. Paulista\",\n \"number\": \"200\",\n \"neighborhood\": \"Bela Vista\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\"\n },\n \"financialOwnerDetails\": {\n \"ownerDeclaredIncome\": \"10000.00\"\n }\n }\n ],\n \"webhookUrl\": \"https://meusite.com/webhook\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 FINISHED", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": \"FINISHED\",\n \"formId\": \"form_xxx\",\n \"sendStatus\": \"SENT\",\n \"proposalId\": \"prop_xxx\"\n}", "cookie": [] } ] }, { "name": "Buscar Proposta", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "proposals", ":id" ], "raw": "{{base_url}}/v1/proposals/:id", "variable": [ { "key": "id", "value": "form_xxx" } ] }, "description": "Retorna o status e os dados de uma proposta de cadastro específica pelo seu ID.\n\n# Consultar proposta\n\n`:id` = formId." }, "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 \"formId\": \"form_xxx\",\n \"proposalStatus\": \"FINISHED\",\n \"pendingFields\": [],\n \"metaData\": {}\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 \"code\": \"FORM_NOT_FOUND\",\n \"message\": \"Formulário não encontrado\"\n}", "cookie": [] } ] }, { "name": "Listar Subcontas", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "accounts", "subaccounts" ], "raw": "{{base_url}}/v1/accounts/subaccounts" }, "description": "Lista todas as subcontas vinculadas à conta principal, com seus dados e status.\n\n# Listar subcontas\n\n**Auth:** Bearer M2M (master)." }, "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 \"accountNumber\": \"123456\",\n \"name\": \"Subconta A\",\n \"status\": \"ACTIVE\"\n }\n ]\n}", "cookie": [] } ] } ] }, { "name": "Carteira", "description": "Consulte seu saldo disponível e acompanhe todos os lançamentos financeiros da sua conta — entradas, saídas, taxas e repasses.", "item": [ { "name": "Consultar Saldo", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "balance" ], "raw": "{{base_url}}/v1/wallet/balance?accountId=", "query": [ { "key": "accountId", "value": "", "description": "M2M: conta específica ou lista separada por vírgula", "disabled": true } ] }, "description": "Retorna o saldo disponível e a atualizar na carteira da conta autenticada.\n\n# Consultar saldo da carteira\n\nRetorna o saldo disponível para saque, o saldo pendente (pagamentos ainda sendo processados) e o total da conta. Contas M2M podem consultar o saldo de subcontas passando `accountId`.\n\n| Parâmetro | Obrig. | Descrição |\n|---|---|---|\n| `accountId` | ❌ | M2M: número da subconta ou lista separada por vírgula |" }, "response": [ { "name": "200 conta própria", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"availableBalance\": 150.0,\n \"pendingBalance\": 30.0,\n \"totalBalance\": 180.0\n}", "cookie": [] }, { "name": "200 M2M multi-conta", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"masterAccountId\": \"m_xxx\",\n \"balances\": [\n {\n \"accountNumber\": \"123456\",\n \"name\": \"Subconta A\",\n \"balance\": 100.0\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 \"code\": \"ACCOUNT_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Listar Transações", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "transactions" ], "raw": "{{base_url}}/v1/wallet/transactions?limit=15&lastKey=&startDate=&endDate=&type=&category=&accountId=", "query": [ { "key": "limit", "value": "15", "description": "default 15", "disabled": true }, { "key": "lastKey", "value": "", "description": "token base64 de paginação", "disabled": true }, { "key": "startDate", "value": "", "description": "ISO 8601", "disabled": true }, { "key": "endDate", "value": "", "description": "ISO 8601", "disabled": true }, { "key": "type", "value": "", "description": "CREDIT | DEBIT", "disabled": true }, { "key": "category", "value": "", "description": "PAYMENT|PIX_IN|PIX_OUT|WITHDRAWAL|SPLIT_IN|REFUND|FEE_COLLECTION", "disabled": true }, { "key": "accountId", "value": "", "description": "M2M: conta específica", "disabled": true } ] }, "description": "Lista o extrato de transações da carteira com suporte a filtros por data e paginação.\n\n# Listar extrato da carteira\n\nRetorna todos os lançamentos financeiros paginados: pagamentos recebidos, PIX enviados e recebidos, saques, repasses, estornos e taxas. Use os filtros para refinar o período ou o tipo de lançamento.\n\n| Parâmetro | Obrig. | Descrição |\n|---|---|---|\n| `limit` | ❌ | Quantidade por página (padrão 15) |\n| `lastKey` | ❌ | Token de paginação retornado na resposta anterior |\n| `startDate` | ❌ | Data inicial (ISO 8601) |\n| `endDate` | ❌ | Data final (ISO 8601) |\n| `type` | ❌ | `CREDIT` (entradas) ou `DEBIT` (saídas) |\n| `category` | ❌ | `PAYMENT` `PIX_IN` `PIX_OUT` `WITHDRAWAL` `SPLIT_IN` `REFUND` `FEE_COLLECTION` |\n| `accountId` | ❌ | M2M: conta específica |" }, "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 \"transactionId\": \"txn_xxx\",\n \"type\": \"CREDIT\",\n \"category\": \"PAYMENT\",\n \"amount\": 100.0,\n \"title\": \"Pagamento PIX recebido\",\n \"paymentMethod\": \"PIX\",\n \"chargeId\": \"cha_xxx\",\n \"subscriptionId\": null,\n \"endToEndId\": \"E...\",\n \"customer\": {\n \"name\": \"João Silva\",\n \"taxId\": \"***.***.***-**\",\n \"customerId\": \"cus_xxx\"\n },\n \"grossAmount\": 100.0,\n \"feeAmount\": 0.99,\n \"createdAt\": \"2024-01-15T10:30:00Z\"\n }\n ],\n \"pagination\": {\n \"total\": 150,\n \"limit\": 15,\n \"hasMore\": true,\n \"lastKey\": \"eyJ...\"\n }\n}", "cookie": [] } ] }, { "name": "Anotar Transação", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"note\": \"Pagamento referente ao pedido #001\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "transactions", ":transactionId" ], "raw": "{{base_url}}/v1/wallet/transactions/:transactionId", "variable": [ { "key": "transactionId", "value": "", "description": "ID da transação a anotar" } ] }, "description": "Adiciona uma anotação interna a uma transação específica para controle próprio.\n\n# Anotar transação\n\nGrava uma observação livre na transação. Útil para controle interno (conciliação, referência de pedido, etc.).\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `note` | ✅ | string | Texto da anotação (máx. 500 caracteres) |\n\n**Erros:** `400 MISSING_NOTE`, `400 INVALID_NOTE`, `404 TRANSACTION_NOT_FOUND`." }, "response": [ { "name": "200", "originalRequest": { "method": "PATCH", "header": [], "url": { "raw": "" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"transactionId\": \"txn_xxx\",\n \"note\": \"Pagamento referente ao pedido #001\",\n \"message\": \"Observação salva com sucesso\"\n}", "cookie": [] }, { "name": "404", "originalRequest": { "method": "PATCH", "header": [], "url": { "raw": "" } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"TRANSACTION_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Listar Recebimentos", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "receivables" ], "raw": "{{base_url}}/v1/wallet/receivables" }, "description": "Lista os recebimentos futuros previstos, com valor e data estimada de liquidação.\n\n# Listar recebimentos\n\nRetorna os valores a receber (pagamentos ainda em liquidação) com a data prevista de disponibilização na carteira." }, "response": [] }, { "name": "Consultar Agenda do Dia", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "receivables-calendar", ":day" ], "raw": "{{base_url}}/v1/wallet/receivables-calendar/:day", "variable": [ { "key": "day", "value": "", "description": "Data no formato YYYY-MM-DD" } ] }, "description": "Retorna os recebimentos previstos para um dia específico.\n\n# Consultar agenda do dia\n\nRetorna o total e o detalhamento dos recebimentos previstos para a data informada em `:day` (formato `YYYY-MM-DD`)." }, "response": [] } ] }, { "name": "Saques", "description": "Transfira dinheiro da sua conta ValidaPay para qualquer chave PIX, acompanhe os saques realizados e valide chaves antes de enviar.", "item": [ { "name": "Solicitar Saque", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "withdraw" ], "raw": "{{base_url}}/v1/wallet/withdraw" }, "description": "Solicita a transferência do saldo disponível para a conta bancária cadastrada.\n\n# Realizar saque via PIX\n\nTransfere o valor solicitado do saldo disponível da sua carteira para uma chave PIX de destino. O saldo deve ser suficiente para cobrir o valor mais as taxas aplicáveis. O processamento é realizado em instantes durante o horário bancário.\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `amount` | ✅ | number | Valor a sacar em reais (maior que zero) |\n| `pixKey` | ✅ | string | Chave PIX do destinatário |\n| `pixKeyType` | ✅ | string | Tipo da chave: `CPF` `CNPJ` `EMAIL` `PHONE` `EVP` |\n| `documentNumber` | ❌ | string | CPF ou CNPJ do titular da chave destino |\n| `accountId` | ❌ | string | M2M: número da subconta de origem |", "body": { "mode": "raw", "raw": "{\n \"amount\": 500.0,\n \"pixKey\": \"joao@email.com\",\n \"pixKeyType\": \"EMAIL\",\n \"documentNumber\": \"12345678901\",\n \"accountId\": null\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 \"withdrawalId\": \"wth_xxx\",\n \"amount\": 500.0,\n \"status\": \"PROCESSING\",\n \"pixKey\": \"joao@email.com\",\n \"createdAt\": \"2024-01-15T10:30:00Z\"\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 \"code\": \"INSUFFICIENT_BALANCE\"\n}", "cookie": [] } ] }, { "name": "Listar Saques", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "withdrawals" ], "raw": "{{base_url}}/v1/wallet/withdrawals?limit=15&lastKey=&startDate=&endDate=&accountId=", "query": [ { "key": "limit", "value": "15", "description": "Quantidade por página (padrão 15)", "disabled": true }, { "key": "lastKey", "value": "", "description": "Token de paginação retornado na resposta anterior", "disabled": true }, { "key": "startDate", "value": "", "description": "Data inicial (ISO 8601)", "disabled": true }, { "key": "endDate", "value": "", "description": "Data final (ISO 8601)", "disabled": true }, { "key": "accountId", "value": "", "description": "M2M: conta específica", "disabled": true } ] }, "description": "Lista todos os saques solicitados com status, valor e data de cada transferência.\n\n# Listar saques\n\nRetorna o histórico de saques realizados na conta, com status, valor, chave PIX de destino e data de cada operação. Útil para conciliação e auditoria financeira.\n\n| Parâmetro | Obrig. | Descrição |\n|---|---|---|\n| `limit` | ❌ | Quantidade por página (padrão 15) |\n| `lastKey` | ❌ | Token de paginação |\n| `startDate` | ❌ | Data inicial (ISO 8601) |\n| `endDate` | ❌ | Data final (ISO 8601) |\n| `accountId` | ❌ | M2M: conta específica |" }, "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 \"withdrawalId\": \"wth_xxx\",\n \"amount\": 500.0,\n \"status\": \"COMPLETED\",\n \"pixKey\": \"joao@email.com\",\n \"pixKeyType\": \"EMAIL\",\n \"createdAt\": \"2024-01-15T10:30:00Z\"\n }\n ],\n \"pagination\": {\n \"total\": 5,\n \"limit\": 15,\n \"hasMore\": false,\n \"lastKey\": null\n }\n}", "cookie": [] } ] }, { "name": "Transferir via Pix", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "pix-transfer" ], "raw": "{{base_url}}/v1/wallet/pix-transfer" }, "description": "Envia um valor diretamente para uma chave Pix, sem precisar de conta bancária cadastrada.\n\n# Enviar transferência PIX\n\nRealiza uma transferência PIX a partir do saldo da carteira para qualquer conta bancária via chave PIX. Diferente do saque, esta operação permite informar um valor livre sem necessidade de pré-cadastro de destinatário.\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `amount` | ✅ | number | Valor da transferência em reais |\n| `pixKey` | ✅ | string | Chave PIX do destinatário |\n| `pixKeyType` | ✅ | string | Tipo da chave: `CPF` `CNPJ` `EMAIL` `PHONE` `EVP` |\n| `description` | ❌ | string | Mensagem/descrição para o destinatário |\n| `accountId` | ❌ | string | M2M: conta de origem |", "body": { "mode": "raw", "raw": "{\n \"amount\": 150.0,\n \"pixKey\": \"11999998888\",\n \"pixKeyType\": \"PHONE\",\n \"description\": \"Pagamento de serviço\",\n \"accountId\": null\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 \"transferId\": \"trf_xxx\",\n \"amount\": 150.0,\n \"status\": \"PROCESSING\",\n \"pixKey\": \"11999998888\",\n \"endToEndId\": \"E...\",\n \"createdAt\": \"2024-01-15T10:30:00Z\"\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 \"code\": \"INSUFFICIENT_BALANCE\"\n}", "cookie": [] } ] }, { "name": "Validar Chave Pix", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "dict" ], "raw": "{{base_url}}/v1/wallet/dict" }, "description": "Verifica se uma chave Pix é válida e retorna os dados do titular antes de realizar uma transferência.\n\n# Consultar chave PIX (DICT)\n\nValida e retorna os dados cadastrados para uma chave PIX no Diretório de Identificadores de Contas Transacionais (DICT) do Banco Central. Use esta rota para confirmar se uma chave existe e exibir o nome do titular ao usuário antes de realizar uma transferência.\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `pixKey` | ✅ | string | Chave PIX a ser consultada |\n| `pixKeyType` | ✅ | string | Tipo da chave: `CPF` `CNPJ` `EMAIL` `PHONE` `EVP` |", "body": { "mode": "raw", "raw": "{\n \"pixKey\": \"joao@email.com\",\n \"pixKeyType\": \"EMAIL\"\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 \"pixKey\": \"joao@email.com\",\n \"pixKeyType\": \"EMAIL\",\n \"owner\": {\n \"name\": \"João da Silva\",\n \"taxId\": \"***.456.789-**\",\n \"type\": \"NATURAL_PERSON\"\n },\n \"account\": {\n \"ispb\": \"12345678\",\n \"bankName\": \"Banco X\",\n \"branch\": \"0001\",\n \"accountNumber\": \"123456-7\",\n \"accountType\": \"CACC\"\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 \"code\": \"PIX_KEY_NOT_FOUND\"\n}", "cookie": [] } ] } ] }, { "name": "Reembolsos", "description": "Solicite o estorno total ou parcial de um pagamento já recebido. O dinheiro retorna ao pagador pelo mesmo meio de pagamento original.", "item": [ { "name": "Solicitar Reembolso", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "refunds" ], "raw": "{{base_url}}/v1/wallet/refunds" }, "description": "Inicia o processo de reembolso de uma cobrança já paga, devolvendo o valor ao meio de pagamento original.\n\n# Solicitar reembolso\n\nIncia o processo de devolução de um pagamento já confirmado. O valor é debitado do seu saldo disponível e devolvido ao cliente pelo mesmo meio de pagamento (PIX ou cartão). Para PIX, informe o `endToEndId`; para cartão, o `chargeId`.\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `endToEndId` | ✅* | string | ID E2E do PIX a ser estornado |\n| `chargeId` | ✅* | string | ID da cobrança a ser estornada |\n| `amount` | ✅ | number | Valor a reembolsar em reais (pode ser parcial) |\n| `reason` | ✅ | string | Motivo: `BANK_ERROR` `FRAUD` `CUSTOMER_REQUEST` `PIX_CHANGE_ERROR` |\n| `accountId` | ❌ | string | M2M: conta específica |\n\n*Pelo menos um dos campos marcados com `✅*` é obrigatório.", "body": { "mode": "raw", "raw": "{\n \"endToEndId\": \"E00000000202401150000000000000001\",\n \"amount\": 100.0,\n \"reason\": \"CUSTOMER_REQUEST\",\n \"chargeId\": \"cha_xxx\",\n \"accountId\": null\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 \"refundId\": \"ref_xxx\",\n \"status\": \"PROCESSING\",\n \"amount\": 100.0,\n \"reason\": \"MD06\"\n}", "cookie": [] }, { "name": "400 excedido", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"REFUND_AMOUNT_EXCEEDED\"\n}", "cookie": [] }, { "name": "400 saldo", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"INSUFFICIENT_BALANCE\"\n}", "cookie": [] } ] }, { "name": "Consultar Reembolso", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "wallet", "refunds" ], "raw": "{{base_url}}/v1/wallet/refunds?limit=15&lastKey=&startDate=&endDate=&accountId=", "query": [ { "key": "limit", "value": "15", "description": "Quantidade por página (padrão 15)", "disabled": true }, { "key": "lastKey", "value": "", "description": "Token de paginação", "disabled": true }, { "key": "startDate", "value": "", "description": "Data inicial (ISO 8601)", "disabled": true }, { "key": "endDate", "value": "", "description": "Data final (ISO 8601)", "disabled": true }, { "key": "accountId", "value": "", "description": "M2M: conta específica", "disabled": true } ] }, "description": "Consulta o status de um reembolso já solicitado.\n\n# Listar reembolsos\n\nRetorna o histórico de reembolsos solicitados, com status de processamento, valor, motivo e cobrança original relacionada.\n\n| Parâmetro | Obrig. | Descrição |\n|---|---|---|\n| `limit` | ❌ | Quantidade por página (padrão 15) |\n| `lastKey` | ❌ | Token de paginação |\n| `startDate` | ❌ | Data inicial (ISO 8601) |\n| `endDate` | ❌ | Data final (ISO 8601) |\n| `accountId` | ❌ | M2M: conta específica |" }, "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 \"refundId\": \"ref_xxx\",\n \"status\": \"COMPLETED\",\n \"amount\": 100.0,\n \"reason\": \"CUSTOMER_REQUEST\",\n \"chargeId\": \"cha_xxx\",\n \"endToEndId\": \"E...\",\n \"createdAt\": \"2024-01-15T10:30:00Z\"\n }\n ],\n \"pagination\": {\n \"total\": 3,\n \"limit\": 15,\n \"hasMore\": false,\n \"lastKey\": null\n }\n}", "cookie": [] } ] } ] }, { "name": "Webhooks", "item": [ { "name": "Criar Webhook", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "users", "webhooks" ], "raw": "{{base_url}}/v1/users/webhooks" }, "description": "Cadastra um endereço para receber avisos automáticos sempre que algo acontecer na sua conta, como um pagamento confirmado ou cancelado.\n\n# Registrar webhook\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `url` | ✅ | string | Endpoint HTTPS |\n| `events` | ❌ | string[] | Eventos a escutar (vazio = todos) |\n| `authToken` | ❌ | string | Header de auth enviado nos disparos |\n\n**Eventos:** `charge.created` `payment.success` `payment.failed` `payment.overdue` `subscription.created` `subscription.activated` `subscription.canceled` `subscription.renewed` `subscription.trial` `subscription.upgraded` `subscription.item_added` `subscription.downgrade_scheduled` `onboarding.documentscopy` `onboarding.proposal` `onboarding.backgroundcheck` `onboarding.create` `refund.requested` `refund.confirmed` `refund.failed` `med.infraction.updated` `med.balance.blocked` `med.balance.unblocked` `med.refund.opened` `med.refund.closed`", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://meusite.com/webhook\",\n \"events\": [\n \"charge.created\",\n \"payment.success\",\n \"payment.failed\",\n \"subscription.created\",\n \"subscription.activated\",\n \"subscription.canceled\",\n \"subscription.renewed\"\n ],\n \"authToken\": \"meu-token-secreto\"\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 \"webhookId\": \"wh_xxx\",\n \"url\": \"https://meusite.com/webhook\",\n \"events\": [\n \"payment.success\"\n ],\n \"status\": \"active\",\n \"createdAt\": \"2024-01-15T10:30:00Z\"\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 \"code\": \"VALIDATION_ERROR\",\n \"message\": \"URL inválida\"\n}", "cookie": [] } ] }, { "name": "Listar Webhooks", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "users", "webhooks" ], "raw": "{{base_url}}/v1/users/webhooks" }, "description": "Lista todos os endereços de notificação cadastrados na conta.\n\n# Listar webhooks" }, "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 {\n \"webhookId\": \"wh_xxx\",\n \"url\": \"https://meusite.com/webhook\",\n \"events\": [],\n \"status\": \"active\"\n }\n]", "cookie": [] } ] }, { "name": "Buscar Webhook", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "users", "webhooks", ":id" ], "raw": "{{base_url}}/v1/users/webhooks/:id", "variable": [ { "key": "id", "value": "wh_xxx" } ] }, "description": "Retorna os detalhes de um endereço de notificação específico.\n\n# Consultar webhook" }, "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 \"webhookId\": \"wh_xxx\",\n \"url\": \"https://meusite.com/webhook\",\n \"events\": [],\n \"status\": \"active\"\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 \"code\": \"WEBHOOK_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Atualizar Webhook", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "users", "webhooks", ":id" ], "raw": "{{base_url}}/v1/users/webhooks/:id", "variable": [ { "key": "id", "value": "wh_xxx" } ] }, "description": "Atualiza o endereço ou os eventos que disparam a notificação.\n\n# Atualizar webhook\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `url` | ❌ | string | Novo endpoint |\n| `events` | ❌ | string[] | Novos eventos |\n| `status` | ❌ | string | `active` `inactive` |\n| `authToken` | ❌ | string | Novo token |", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://meusite.com/novo-webhook\",\n \"events\": [\n \"payment.success\",\n \"payment.failed\"\n ],\n \"status\": \"active\",\n \"authToken\": \"novo-token\"\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 \"webhookId\": \"wh_xxx\",\n \"url\": \"https://meusite.com/novo-webhook\",\n \"status\": \"active\"\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 \"code\": \"WEBHOOK_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Remover Webhook", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "DELETE", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "users", "webhooks", ":id" ], "raw": "{{base_url}}/v1/users/webhooks/:id", "variable": [ { "key": "id", "value": "wh_xxx" } ] }, "description": "Remove um endereço de notificação da conta.\n\n# Deletar webhook" }, "response": [ { "name": "200", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "Deletado com sucesso", "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 \"code\": \"WEBHOOK_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Testar Webhook", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "users", "webhooks", "test" ], "raw": "{{base_url}}/v1/users/webhooks/test" }, "description": "Envia um aviso de teste para o endereço configurado, permitindo validar se as notificações estão chegando corretamente.\n\n# Testar webhook (payload fake)\n\nObrigatório `webhookId` ou `url`.\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `webhookId` | ✅* | string | ID do webhook registrado |\n| `url` | ✅* | string | URL alternativa |\n| `entity` | ✅ | string | Tipo de evento para gerar payload |", "body": { "mode": "raw", "raw": "{\n \"webhookId\": \"wh_xxx\",\n \"entity\": \"payment.success\"\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 \"url\": \"https://meusite.com/webhook\",\n \"event\": \"payment.success\",\n \"payload\": {},\n \"response\": {\n \"statusCode\": 200\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 \"success\": false,\n \"error\": \"Connection refused\"\n}", "cookie": [] } ] }, { "name": "Listar Eventos", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "users", "webhooks", "events" ], "raw": "{{base_url}}/v1/users/webhooks/events?limit=50&nextPageToken=&type=", "query": [ { "key": "limit", "value": "50", "description": "1–100, default 50", "disabled": true }, { "key": "nextPageToken", "value": "", "description": "base64url", "disabled": true }, { "key": "type", "value": "", "description": "ex: payment.success", "disabled": true } ] }, "description": "Retorna a lista de todos os eventos disponíveis para receber notificações, como pagamento aprovado, assinatura cancelada, entre outros.\n\n# Histórico de disparos" }, "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 \"eventId\": \"evt_xxx\",\n \"webhookId\": \"wh_xxx\",\n \"type\": \"payment.success\",\n \"status\": \"success\",\n \"attempt\": 1,\n \"responseStatusCode\": 200,\n \"createdAt\": \"2024-01-15T10:30:00Z\"\n }\n ],\n \"count\": 10,\n \"total\": 100,\n \"hasMore\": true,\n \"nextPageToken\": \"eyJ...\"\n}", "cookie": [] } ] }, { "name": "Reprocessar Evento", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "users", "webhooks", "events", ":id", "retry" ], "raw": "{{base_url}}/v1/users/webhooks/events/:id/retry", "variable": [ { "key": "id", "value": "evt_xxx" } ] }, "description": "Reenvia a notificação de um evento que não foi entregue ou precisa ser processado novamente.\n\n# Reenviar disparo\n\n`:id` = webhookEventId." }, "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 \"message\": \"Webhook reenviado com sucesso\",\n \"webhookEventId\": \"evt_xxx\",\n \"attempt\": 2,\n \"status\": \"success\"\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 \"code\": \"WEBHOOK_EVENT_NOT_FOUND\"\n}", "cookie": [] } ] } ] }, { "name": "Produtos", "item": [ { "name": "Criar Produto", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "products" ], "raw": "{{base_url}}/v1/products" }, "description": "Cria um novo produto ou serviço com nome, descrição, preço e configurações de recorrência.\n\n# Criar produto\n\n**Scopes:** `products/write`\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `name` | ✅ | string | Nome do produto |\n| `type` | ❌ | string | `RECURRING` `ONE_TIME` (default RECURRING) |\n| `statementDescriptor` | ❌ | string | max 22 chars |\n| `prices[].amount` | ✅ | number | Valor em reais (> 0) |\n| `prices[].recurrenceType` | ✅ | string | `WEEKLY` `MONTHLY` `QUARTERLY` `SEMIANNUAL` `YEARLY` `ONE_TIME` |\n| `prices[].recurrenceInterval` | ❌ | number | min 1 (ex: 2 = bimestral) |\n| `prices[].trialDays` | ❌ | number | ≥ 0 |\n| `prices[].compareAtPrice` | ❌ | number | 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 \"code\": \"INVALID_PRODUCT_DATA\"\n}", "cookie": [] } ] }, { "name": "Listar Produtos", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "products" ], "raw": "{{base_url}}/v1/products?limit=50&lastKey=&status=&search=", "query": [ { "key": "limit", "value": "50", "description": "", "disabled": true }, { "key": "lastKey", "value": "", "description": "base64", "disabled": true }, { "key": "status", "value": "", "description": "active | inactive", "disabled": true }, { "key": "search", "value": "", "description": "busca por nome", "disabled": true } ] }, "description": "Lista todos os produtos cadastrados com suporte a filtros por status e paginação.\n\n# Listar produtos\n\n**Scopes:** `products/read`" }, "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": { "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id" ], "raw": "{{base_url}}/v1/products/:id", "variable": [ { "key": "id", "value": "prod_xxx" } ] }, "description": "Retorna todos os detalhes de um produto específico, incluindo preço e configurações.\n\n# Consultar produto" }, "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 \"code\": \"PRODUCT_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Atualizar Produto", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id" ], "raw": "{{base_url}}/v1/products/:id", "variable": [ { "key": "id", "value": "prod_xxx" } ] }, "description": "Atualiza as informações de um produto, como nome, descrição ou preço.\n\n# Atualizar produto\n\nMesmos campos de POST (todos opcionais). Para atualizar preço existente, inclua `priceId` no item de `prices[]`.", "body": { "mode": "raw", "raw": "{\n \"name\": \"Plano Premium Plus\",\n \"prices\": [\n {\n \"priceId\": \"price_xxx\",\n \"amount\": 109.9\n },\n {\n \"title\": \"Trimestral\",\n \"amount\": 279.0,\n \"recurrenceType\": \"QUARTERLY\"\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 \"code\": \"PRODUCT_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Remover Produto", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "DELETE", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id" ], "raw": "{{base_url}}/v1/products/:id", "variable": [ { "key": "id", "value": "prod_xxx" } ] }, "description": "Remove um produto que não esteja vinculado a assinaturas ativas.\n\n# Deletar produto" }, "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 \"code\": \"PRODUCT_HAS_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 \"code\": \"PRODUCT_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Arquivar Produto", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "products", ":id", "archive" ], "raw": "{{base_url}}/v1/products/:id/archive", "variable": [ { "key": "id", "value": "prod_xxx" } ] }, "description": "Guarda o produto sem excluí-lo, mantendo o histórico de cobranças vinculadas.\n\n# Arquivar produto" }, "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 \"code\": \"PRODUCT_NOT_FOUND\"\n}", "cookie": [] } ] } ] }, { "name": "Clientes", "item": [ { "name": "Criar Cliente", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "customers" ], "raw": "{{base_url}}/v1/customers" }, "description": "Cria um novo cliente com dados pessoais como nome, CPF/CNPJ, e-mail e endereço.\n\n# Criar cliente\n\n**Scopes:** `customers/write`\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `name` | ✅ | string | Nome completo |\n| `phone` | ✅ | string | E.164 |\n| `email` | ❌ | string | email válido |\n| `document` | ✅ | string | CPF (11) ou CNPJ (14), só dígitos |\n| `upsert` | ❌ | boolean | Se `true`, retorna existente sem erro |", "body": { "mode": "raw", "raw": "{\n \"name\": \"João da Silva\",\n \"phone\": \"+5511999998888\",\n \"email\": \"joao@email.com\",\n \"document\": \"12345678901\",\n \"upsert\": false\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 \"name\": \"João da Silva\",\n \"document\": \"12345678901\",\n \"createdAt\": \"2024-01-15T10:30:00Z\"\n }\n}", "cookie": [] }, { "name": "400 existe", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"CUSTOMER_ALREADY_EXISTS\"\n}", "cookie": [] }, { "name": "400 inválido", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"INVALID_DATA\",\n \"message\": \"Documento inválido\"\n}", "cookie": [] } ] }, { "name": "Listar Clientes", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "customers" ], "raw": "{{base_url}}/v1/customers?limit=15&lastKey=&startDate=&endDate=&document=&search=", "query": [ { "key": "limit", "value": "15", "description": "", "disabled": true }, { "key": "lastKey", "value": "", "description": "base64", "disabled": true }, { "key": "startDate", "value": "", "description": "YYYY-MM-DD", "disabled": true }, { "key": "endDate", "value": "", "description": "YYYY-MM-DD", "disabled": true }, { "key": "document", "value": "", "description": "filtro CPF/CNPJ", "disabled": true }, { "key": "search", "value": "", "description": "busca por nome", "disabled": true } ] }, "description": "Lista todos os clientes cadastrados com suporte a busca por nome, documento e paginação.\n\n# Listar clientes\n\n**Scopes:** `customers/read`" }, "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\": \"João da Silva\"\n }\n ],\n \"pagination\": {\n \"total\": 5,\n \"hasMore\": false\n }\n}", "cookie": [] } ] }, { "name": "Buscar Cliente", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "customers", ":id" ], "raw": "{{base_url}}/v1/customers/:id", "variable": [ { "key": "id", "value": "cus_xxx" } ] }, "description": "Retorna todos os dados cadastrais de um cliente específico pelo seu ID.\n\n# Consultar cliente\n\nRetorna `addresses`, `subscriptions` (com ciclos e upgrades), `ltv`." }, "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 \"customerId\": \"cus_xxx\",\n \"name\": \"João da Silva\",\n \"addresses\": [],\n \"subscriptions\": [],\n \"ltv\": 0\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 \"code\": \"CUSTOMER_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Atualizar Cliente", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "customers", ":id" ], "raw": "{{base_url}}/v1/customers/:id", "variable": [ { "key": "id", "value": "cus_xxx" } ] }, "description": "Atualiza os dados cadastrais de um cliente, como endereço, telefone ou e-mail.\n\n# Atualizar cliente\n\n| Campo | Obrig. | Tipo |\n|---|---|---|\n| `name` | ❌ | string |\n| `email` | ❌ | string |\n| `phone` | ❌ | string |\n| `document` | ❌ | string |", "body": { "mode": "raw", "raw": "{\n \"name\": \"João Silva Atualizado\",\n \"email\": \"novo@email.com\",\n \"phone\": \"+5511988887777\"\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\": \"João Silva Atualizado\"\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 \"code\": \"DOCUMENT_ALREADY_EXISTS\"\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 \"code\": \"CUSTOMER_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Remover Cliente", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "DELETE", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "customers", ":id" ], "raw": "{{base_url}}/v1/customers/:id", "variable": [ { "key": "id", "value": "cus_xxx" } ] }, "description": "Remove o cadastro de um cliente que não possua cobranças ou assinaturas ativas.\n\n# Deletar 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 \"message\": \"Cliente deletado com sucesso\"\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 \"code\": \"CUSTOMER_HAS_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 \"code\": \"CUSTOMER_NOT_FOUND\"\n}", "cookie": [] } ] } ] }, { "name": "Cupons", "item": [ { "name": "Criar Cupom", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "coupons" ], "raw": "{{base_url}}/v1/coupons" }, "description": "Cria um cupom de desconto com valor fixo ou percentual, limite de usos e período de validade.\n\n# Criar cupom\n\n**Scopes:** `coupons/write`\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `code` | ✅ | string | Código único (case-insensitive), max 50 |\n| `discountType` | ✅ | string | `PERCENTAGE` `FIXED` |\n| `discountValue` | ✅ | number | > 0; ≤ 100 se PERCENTAGE |\n| `maxCycles` | ❌ | number | Ciclos com desconto (null = infinito) |\n| `maxRedemptions` | ❌ | number | Usos totais (null = ilimitado) |\n| `minAmount` | ❌ | number | Valor mínimo p/ aplicar |\n| `maxDiscount` | ❌ | number | Teto de desconto em reais |\n| `validFrom`/`validUntil` | ❌ | string | ISO 8601 |\n| `productIds` | ❌ | string[] | Restringe a produtos |\n| `firstTimeOnly` | ❌ | boolean | Só 1ª compra |\n| `appliesTo` | ❌ | string | `RECURRING` `ONE_TIME` `ALL` |", "body": { "mode": "raw", "raw": "{\n \"code\": \"PROMO10\",\n \"name\": \"Desconto de 10%\",\n \"description\": \"Válido somente para novos clientes\",\n \"discountType\": \"PERCENTAGE\",\n \"discountValue\": 10,\n \"maxCycles\": 3,\n \"maxRedemptions\": 100,\n \"minAmount\": 50.0,\n \"maxDiscount\": 30.0,\n \"validFrom\": \"2024-01-01T00:00:00Z\",\n \"validUntil\": \"2024-12-31T23:59:59Z\",\n \"productIds\": [\n \"prod_xxx\"\n ],\n \"firstTimeOnly\": true,\n \"appliesTo\": \"RECURRING\"\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 \"couponId\": \"cou_xxx\",\n \"code\": \"PROMO10\",\n \"status\": \"ACTIVE\"\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 \"code\": \"COUPON_CODE_DUPLICATE\"\n}", "cookie": [] } ] }, { "name": "Listar Cupons", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "coupons" ], "raw": "{{base_url}}/v1/coupons?limit=15&lastKey=&status=&search=", "query": [ { "key": "limit", "value": "15", "description": "", "disabled": true }, { "key": "lastKey", "value": "", "description": "base64", "disabled": true }, { "key": "status", "value": "", "description": "ACTIVE | PAUSED | INACTIVE", "disabled": true }, { "key": "search", "value": "", "description": "busca", "disabled": true } ] }, "description": "Lista todos os cupons cadastrados com informações de uso e validade.\n\n# Listar cupons\n\n**Scopes:** `coupons/read`" }, "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 \"couponId\": \"cou_xxx\",\n \"code\": \"PROMO10\"\n }\n ],\n \"pagination\": {\n \"total\": 3,\n \"hasMore\": false\n }\n}", "cookie": [] } ] }, { "name": "Buscar Cupom", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "coupons", ":couponId" ], "raw": "{{base_url}}/v1/coupons/:couponId", "variable": [ { "key": "couponId", "value": "cou_xxx" } ] }, "description": "Retorna os detalhes de um cupom específico, incluindo regras de uso e quantidade restante.\n\n# Consultar cupom" }, "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 \"couponId\": \"cou_xxx\",\n \"code\": \"PROMO10\",\n \"status\": \"ACTIVE\"\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 \"code\": \"COUPON_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Atualizar Cupom", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "coupons", ":couponId" ], "raw": "{{base_url}}/v1/coupons/:couponId", "variable": [ { "key": "couponId", "value": "cou_xxx" } ] }, "description": "Atualiza as configurações de um cupom, como validade ou limite de usos.\n\n# Atualizar cupom\n\nMesmos campos de POST exceto `code` (todos opcionais).", "body": { "mode": "raw", "raw": "{\n \"name\": \"Desconto de 15%\",\n \"discountValue\": 15,\n \"maxRedemptions\": 200\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 \"couponId\": \"cou_xxx\",\n \"discountValue\": 15\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 \"code\": \"COUPON_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Atualizar Cupom Parcialmente", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "coupons", ":couponId" ], "raw": "{{base_url}}/v1/coupons/:couponId", "variable": [ { "key": "couponId", "value": "cou_xxx" } ] }, "description": "Atualiza parcialmente um cupom, alterando apenas os campos enviados na requisição.\n\n# Alterar status do cupom\n\n| Campo | Obrig. | Tipo | Valores |\n|---|---|---|---|\n| `status` | ✅ | string | `ACTIVE` `PAUSED` `INACTIVE` |", "body": { "mode": "raw", "raw": "{\n \"status\": \"PAUSED\"\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 \"couponId\": \"cou_xxx\",\n \"status\": \"PAUSED\"\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 \"code\": \"COUPON_INACTIVE_FINAL\",\n \"message\": \"Cupom inativo não pode ser reativado\"\n}", "cookie": [] } ] }, { "name": "Remover Cupom", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "DELETE", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "coupons", ":couponId" ], "raw": "{{base_url}}/v1/coupons/:couponId", "variable": [ { "key": "couponId", "value": "cou_xxx" } ] }, "description": "Remove um cupom, impedindo novos usos sem afetar descontos já aplicados.\n\n# Deletar cupom" }, "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 \"code\": \"COUPON_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Validar Cupom", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "coupons", ":couponId", "validate" ], "raw": "{{base_url}}/v1/coupons/:couponId/validate", "variable": [ { "key": "couponId", "value": "PROMO10" } ] }, "description": "Verifica se um cupom pode ser usado e retorna o valor do desconto que será aplicado.\n\n# Validar cupom (público)\n\n**Auth:** nenhuma. `:id` = código do cupom.\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `amount` | ❌ | number | Valor para validar contra minAmount |\n| `productIds` | ❌ | string[] | Produtos do carrinho |\n| `chargeType` | ❌ | string | `RECURRING` `ONE_TIME` (default RECURRING) |\n| `customerDocument` | ❌ | string | Para validar firstTimeOnly |", "body": { "mode": "raw", "raw": "{\n \"amount\": 99.9,\n \"productIds\": [\n \"prod_xxx\"\n ],\n \"chargeType\": \"RECURRING\",\n \"customerDocument\": \"12345678901\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 válido", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"valid\": true,\n \"coupon\": {\n \"code\": \"PROMO10\",\n \"discountType\": \"PERCENTAGE\",\n \"discountValue\": 10\n }\n}", "cookie": [] }, { "name": "200 inválido", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"valid\": false,\n \"reason\": \"COUPON_NOT_FOUND\"\n}", "cookie": [] } ] } ] }, { "name": "Cobranças", "item": [ { "name": "Criar Cobrança Pix", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "X-Sub-Account", "value": "{{subaccount_number}}", "disabled": true, "description": "Número da subconta para cobrar em nome dela" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "charges" ], "raw": "{{base_url}}/v1/charges" }, "description": "Cria uma cobrança Pix para seu cliente.\n\n# Criar cobrança\n\nCria uma cobrança avulsa para o seu cliente. O método de pagamento é definido no campo `paymentMethod` — escolha entre Pix, boleto ou cartão de crédito.\n\n**Autenticação:** token de acesso (Bearer). Se você opera como conta principal e quer emitir a cobrança em nome de uma subconta, informe o número dela no cabeçalho `X-Sub-Account`.\n\n**Métodos de pagamento disponíveis:**\n\n| Método (`paymentMethod`) | Como o cliente paga |\n|---|---|\n| `pix` | QR Code / Pix Copia e Cola, com pagamento na hora |\n| `boleto` | Boleto bancário com data de vencimento |\n| `creditcard` | Cartão de crédito, à vista ou parcelado |\n\n**Campos principais:**\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `paymentMethod` | ✅ | string | Método de pagamento: `pix`, `boleto` ou `creditcard` |\n| `amount` | ✅ | number | Valor da cobrança, em reais |\n| `title` | ✅ | string | Título da cobrança (2 a 100 caracteres) |\n| `description` | ❌ | string | Descrição exibida ao cliente (até 500 caracteres) |\n| `expiration` | ❌ | string | Prazo máximo de pagamento após o vencimento. Formato: `YYYY-MM-DD` — ex: `\"2026-12-31\"`. Se omitido: sem expiração. **Deve ser posterior a `dueDate` quando ambos forem informados.** |\n| `dueDate` | ❌ | string | Data de vencimento do Pix (sem juros até essa data). Formato: `YYYY-MM-DD` — ex: `\"2026-12-01\"`. Se omitido: hoje + 30 dias. |\n| `boletoDueDays` | ❌ | number | Prazo do boleto em dias (1 a 60) — alternativa ao `dueDate` |\n| `customer` | ❌ | object | Dados do cliente (nome, documento, e-mail, telefone) |\n| `customer.address` | ❌ | object | Endereço do cliente — obrigatório para boleto |\n| `boletoInstructions.fine` | ❌ | number | Multa por atraso, em % (0.1 a 100) |\n| `boletoInstructions.interest` | ❌ | number | Juros mensais por atraso, em % |\n| `boletoInstructions.discount` | ❌ | object | Desconto: `amount`, `modality` (`fixed`/`percent`) e `limitDate` (formato `YYYY-MM-DD`, deve ser anterior ao `dueDate`) |\n| `card` | ✅* | object | Dados do cartão (número, CVV, nome, validade no formato `MM/YYYY` — ex: `\"12/2027\"`) — obrigatório para cartão |\n| `tokenId` | ❌ | string | Token de um cartão já salvo (alternativa a `card`) |\n| `installments` | ❌ | number | Número de parcelas (1 a 12, padrão 1) |\n| `passFeesToCustomer` | ❌ | boolean | Repassa as taxas ao cliente |\n| `freeInstallments` | ❌ | number | Parcelas sem juros (1 a 12, padrão 1) |\n| `split` | ❌ | array | Divisão do valor entre contas (`type`, `accountNumber`, `amount`) |\n| `metadata` | ❌ | object | Dados adicionais de sua escolha |\n| `externalTxid` | ❌ | string | Identificador externo único da cobrança |\n| `nfConfigId` | ❌ | string | Configuração de nota fiscal a ser usada |\n\n> Os campos marcados com `*` são obrigatórios conforme o método de pagamento escolhido.\n\n**⚠️ Relação entre `dueDate` e `expiration`:**\n\n- `dueDate` = data até a qual o cliente paga sem juros/multa\n- `expiration` = prazo máximo para pagamento após o vencimento (com juros/multa se configurados)\n- **Regra:** `expiration` deve ser uma data posterior a `dueDate`\n- Se `expiration` for omitido, o padrão é `dueDate` + 30 dias\n\nExemplo com ambos os campos:\n```json\n{\n \"paymentMethod\": \"pix\",\n \"amount\": 100.0,\n \"title\": \"Mensalidade Junho\",\n \"dueDate\": \"2026-07-01\",\n \"expiration\": \"2026-07-31\"\n}\n```\n\n**Scope OAuth necessário:** `pix.cob/write`", "body": { "mode": "raw", "raw": "{\n \"paymentMethod\": \"pix\",\n\n \"amount\": 100.0,\n \"title\": \"Cobrança PIX\",\n \"description\": \"Referente ao pedido #001\",\n \"expiration\": \"2026-12-31\",\n\n \"customer\": {\n \"documentNumber\": \"12345678901\",\n \"name\": \"João da Silva\",\n \"email\": \"joao@email.com\",\n \"phone\": \"+5511999998888\",\n \"cep\": \"01310100\"\n },\n\n \"passFeesToCustomer\": false,\n \"installments\": 1,\n \"freeInstallments\": 1,\n\n \"split\": [\n {\n \"type\": \"percentage\",\n \"accountNumber\": \"123456\",\n \"amount\": 10\n }\n ],\n\n \"metadata\": {\n \"orderId\": \"ORD-001\"\n },\n \"externalTxid\": \"txid-externo-unico\",\n \"nfConfigId\": null\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "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 \"chargeId\": \"cha_xxx\",\n \"emv\": \"00020126580014...\",\n \"qrCode\": \"data:image/png;base64,iVBORw0KGgo...\",\n \"metadata\": {}\n}", "cookie": [] }, { "name": "400 split", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"SPLIT_EXCEEDS_NET_AMOUNT\"\n}", "cookie": [] }, { "name": "404 chave", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"PIX_KEY_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Criar Cobrança Boleto", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "X-Sub-Account", "value": "{{subaccount_number}}", "disabled": true, "description": "Número da subconta para cobrar em nome dela" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "charges" ], "raw": "{{base_url}}/v1/charges" }, "description": "Cria uma cobrança via boleto bancário para seu cliente.\n\n# Criar cobrança\n\nCria uma cobrança avulsa para o seu cliente. O método de pagamento é definido no campo `paymentMethod` — escolha entre Pix, boleto ou cartão de crédito.\n\n**Autenticação:** token de acesso (Bearer). Se você opera como conta principal e quer emitir a cobrança em nome de uma subconta, informe o número dela no cabeçalho `X-Sub-Account`.\n\n**Métodos de pagamento disponíveis:**\n\n| Método (`paymentMethod`) | Como o cliente paga |\n|---|---|\n| `pix` | QR Code / Pix Copia e Cola, com pagamento na hora |\n| `boleto` | Boleto bancário com data de vencimento |\n| `creditcard` | Cartão de crédito, à vista ou parcelado |\n\n**Campos principais:**\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `paymentMethod` | ✅ | string | Método de pagamento: `pix`, `boleto` ou `creditcard` |\n| `amount` | ✅ | number | Valor da cobrança, em reais |\n| `title` | ✅ | string | Título da cobrança (2 a 100 caracteres) |\n| `description` | ❌ | string | Descrição exibida ao cliente (até 500 caracteres) |\n| `dueDate` | ❌ | string | Data de vencimento do boleto. Formato: `YYYY-MM-DD` — ex: `\"2026-07-30\"`. Se omitido: hoje + 30 dias. |\n| `boletoDueDays` | ❌ | number | Prazo em dias até o vencimento (1 a 60) — alternativa ao `dueDate` |\n| `expirationAfterDueDate` | ❌ | number | Dias extras para pagamento após o vencimento (padrão: 30) |\n| `customer` | ❌ | object | Dados do cliente |\n| `customer.name` | ❌ | string | Nome completo |\n| `customer.documentNumber` | ❌ | string | CPF (11 dígitos) ou CNPJ (14 dígitos) |\n| `customer.email` | ❌ | string | E-mail |\n| `customer.phone` | ❌ | string | Telefone com DDI (+55...) |\n| `customer.address` | ✅ | object | **Obrigatório para boleto.** Endereço completo do pagador |\n| `customer.address.street` | ✅ | string | Logradouro |\n| `customer.address.number` | ✅ | string | Número |\n| `customer.address.neighborhood` | ✅ | string | Bairro |\n| `customer.address.city` | ✅ | string | Cidade |\n| `customer.address.state` | ✅ | string | UF (2 letras, ex: `\"SP\"`) |\n| `customer.address.zipCode` | ✅ | string | CEP (8 dígitos, ex: `\"01310100\"`) |\n| `customer.address.complement` | ❌ | string | Complemento |\n| `boletoInstructions.fine` | ❌ | number | Multa por atraso em % (0.1 a 100) |\n| `boletoInstructions.interest` | ❌ | number | Juros mensais por atraso em % |\n| `boletoInstructions.discount.amount` | ❌ | number | Valor do desconto |\n| `boletoInstructions.discount.modality` | ❌ | string | `\"fixed\"` (valor fixo) ou `\"percent\"` (percentual) |\n| `boletoInstructions.discount.limitDate` | ❌ | string | Data limite para o desconto. Formato: `YYYY-MM-DD` — ex: `\"2026-07-28\"`. Deve ser anterior ao `dueDate`. |\n| `split` | ❌ | array | Divisão do valor entre contas (`type`, `accountNumber`, `amount`) |\n| `metadata` | ❌ | object | Dados adicionais de sua escolha |\n| `externalTxid` | ❌ | string | Identificador externo único da cobrança |\n| `nfConfigId` | ❌ | string | Configuração de nota fiscal a ser usada |\n\n**⚠️ `customer.address` é obrigatório para boleto.** Sem o endereço completo do pagador a emissão falhará.\n\n**Scope OAuth necessário:** `checkouts/write`", "body": { "mode": "raw", "raw": "{\n \"paymentMethod\": \"boleto\",\n \"amount\": 250.0,\n \"title\": \"Fatura de Serviços\",\n \"description\": \"Referente ao mês de janeiro\",\n \"dueDate\": \"2026-07-30\",\n \"boletoDueDays\": 3,\n \"expirationAfterDueDate\": 30,\n \"customer\": {\n \"name\": \"João da Silva\",\n \"documentNumber\": \"12345678901\",\n \"email\": \"joao@email.com\",\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 \"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 \"passFeesToCustomer\": false,\n \"split\": [\n {\n \"type\": \"percentage\",\n \"accountNumber\": \"123456\",\n \"amount\": 10\n }\n ],\n \"metadata\": {\n \"orderId\": \"ORD-001\"\n },\n \"externalTxid\": \"txid-externo-unico\",\n \"nfConfigId\": null\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 Boleto", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"chargeId\": \"cha_xxx\",\n \"digitableLine\": \"03399.09097 74000.759406 18000.011230 3 97560000025000\",\n \"barCode\": \"03393975600000250009090974000759401800001123\",\n \"dueDate\": \"2026-07-30\",\n \"pdfUrl\": \"/v1/charges/cha_xxx/boleto.pdf\"\n}", "cookie": [] } ] }, { "name": "Criar Cobrança com Cartão", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "X-Sub-Account", "value": "{{subaccount_number}}", "disabled": true, "description": "Número da subconta para cobrar em nome dela" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "charges" ], "raw": "{{base_url}}/v1/charges" }, "description": "Cria uma cobrança via cartão de crédito para seu cliente.\n\n# Criar cobrança\n\nCria uma cobrança avulsa para o seu cliente. O método de pagamento é definido no campo `paymentMethod` — escolha entre Pix, boleto ou cartão de crédito.\n\n**Autenticação:** token de acesso (Bearer). Se você opera como conta principal e quer emitir a cobrança em nome de uma subconta, informe o número dela no cabeçalho `X-Sub-Account`.\n\n**Métodos de pagamento disponíveis:**\n\n| Método (`paymentMethod`) | Como o cliente paga |\n|---|---|\n| `pix` | QR Code / Pix Copia e Cola, com pagamento na hora |\n| `boleto` | Boleto bancário com data de vencimento |\n| `creditcard` | Cartão de crédito, à vista ou parcelado |\n\n**Cartão — duas formas de enviar:**\n\n- **`paymentMethodId`** (recomendado): ID de um cartão já tokenizado via `/v1/payment-methods/tokenize`. Não trafega dados sensíveis.\n- **`card`** (dados brutos): o cartão é tokenizado e **salvo** automaticamente no cliente, ficando reutilizável como `paymentMethodId` nas próximas cobranças.\n\n> ⚠️ **`customer` é obrigatório quando o cartão é enviado para pagamento** (via `card` ou `paymentMethodId`), pois o cartão é vinculado a um cliente — informe ao menos `customer.documentNumber`. Se você apenas **cria** a cobrança (sem cartão, para capturar depois), `customer` é opcional e o retorno traz `installmentOptions`.\n\n**Campos principais:**\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `paymentMethod` | ✅ | string | Método de pagamento: `pix`, `boleto` ou `creditcard` |\n| `amount` | ✅ | number | Valor da cobrança, em reais |\n| `title` | ✅ | string | Título da cobrança (2 a 100 caracteres) |\n| `description` | ❌ | string | Descrição exibida ao cliente (até 500 caracteres) |\n| `customer` | ✅* | object | Dados do cliente. Obrigatório quando há `card` ou `paymentMethodId`. Campos: `name`, `documentNumber`, `email`, `phone`, `address` |\n| `paymentMethodId` | ✅* | string | ID de cartão tokenizado. Alternativa a `card`. |\n| `card` | ✅* | object | Dados brutos do cartão. Alternativa a `paymentMethodId`. Campos: `number` (13-19 dígitos), `cvv` (3-4 dígitos), `name`, `expiration` (`MM/YYYY`) |\n| `installments` | ❌ | number | Número de parcelas (1 a 12, padrão 1) |\n| `passFeesToCustomer` | ❌ | boolean | Repassa as taxas ao cliente |\n| `freeInstallments` | ❌ | number | Parcelas sem juros (1 a 12, padrão 1) |\n| `split` | ❌ | array | Divisão do valor entre contas (`type`, `accountNumber`, `amount`) |\n| `metadata` | ❌ | object | Dados adicionais de sua escolha |\n| `nfConfigId` | ❌ | string | Configuração de nota fiscal a ser usada |\n\n> Os campos marcados com `*` são obrigatórios conforme o cenário. Para cobrar cartão, envie `card` **ou** `paymentMethodId` (nunca os dois) e inclua `customer`.\n\n**Scope OAuth necessário:** `checkouts/write`", "body": { "mode": "raw", "raw": "{\n \"paymentMethod\": \"creditcard\",\n \"amount\": 399.9,\n \"title\": \"Compra avulsa\",\n \"description\": \"Produto Premium\",\n \"customer\": {\n \"name\": \"João da Silva\",\n \"documentNumber\": \"12345678901\",\n \"email\": \"joao@email.com\",\n \"phone\": \"+5511999998888\"\n },\n \"paymentMethodId\": \"pm_abc123\",\n \"installments\": 3,\n \"passFeesToCustomer\": false,\n \"freeInstallments\": 1,\n \"metadata\": {\n \"orderId\": \"ORD-001\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 Cartão (cobrança imediata)", "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 \"chargeId\": \"cha_xxx\",\n \"status\": \"paid\"\n}", "cookie": [] }, { "name": "200 Link (sem cartão)", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"chargeId\": \"cha_xxx\",\n \"installmentOptions\": [\n { \"installments\": 1, \"amount\": 399.9, \"total\": 399.9 },\n { \"installments\": 2, \"amount\": 199.95, \"total\": 399.9 },\n { \"installments\": 3, \"amount\": 133.3, \"total\": 399.9 }\n ]\n}", "cookie": [] }, { "name": "402 Recusado", "originalRequest": { "method": "GET", "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_xxx\",\n \"status\": \"failed\",\n \"error\": \"declined\"\n}", "cookie": [] }, { "name": "400 tokenização", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"CARD_TOKENIZATION_FAILED\"\n}", "cookie": [] }, { "name": "400 customer obrigatório", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"message\": \"Cliente é obrigatório para salvar cartão\",\n \"code\": \"CUSTOMER_REQUIRED\"\n}", "cookie": [] }, { "name": "400 cartão não tokenizado", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"message\": \"Cartão não tokenizado no provider ativo\",\n \"code\": \"CARD_NOT_TOKENIZED\"\n}", "cookie": [] } ] }, { "name": "Listar Cobranças", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "charges" ], "raw": "{{base_url}}/v1/charges?limit=15&lastKey=&startDate=&endDate=&status=&search=&document=&paymentMethod=&priceId=&productId=", "query": [ { "key": "limit", "value": "15", "description": "", "disabled": true }, { "key": "lastKey", "value": "", "description": "base64", "disabled": true }, { "key": "startDate", "value": "", "description": "YYYY-MM-DD", "disabled": true }, { "key": "endDate", "value": "", "description": "YYYY-MM-DD", "disabled": true }, { "key": "status", "value": "", "description": "PENDING|PAID|FAILED|CANCELED|ARCHIVED", "disabled": true }, { "key": "search", "value": "", "description": "nome/doc", "disabled": true }, { "key": "document", "value": "", "description": "CPF/CNPJ", "disabled": true }, { "key": "paymentMethod", "value": "", "description": "PIX|BOLETO|CREDIT_CARD", "disabled": true }, { "key": "priceId", "value": "", "description": "", "disabled": true }, { "key": "productId", "value": "", "description": "", "disabled": true } ] }, "description": "Lista todas as cobranças da conta com filtros por status, método de pagamento e data.\n\n# Listar cobranças" }, "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 \"chargeId\": \"cha_xxx\",\n \"status\": \"PAID\",\n \"amount\": 100.0\n }\n ],\n \"pagination\": {\n \"total\": 20,\n \"hasMore\": true,\n \"lastKey\": \"eyJ...\"\n }\n}", "cookie": [] } ] }, { "name": "Buscar Cobrança", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "charges", ":chargeId" ], "raw": "{{base_url}}/v1/charges/:chargeId", "variable": [ { "key": "chargeId", "value": "cha_xxx" } ] }, "description": "Retorna o status atualizado e todos os detalhes de uma cobrança, incluindo se já foi paga.\n\n# Consultar 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 \"chargeId\": \"cha_xxx\",\n \"status\": \"PAID\",\n \"amount\": 100.0,\n \"currency\": \"BRL\",\n \"paymentType\": \"PIX\",\n \"provider\": \"MAL\",\n \"accountNumber\": \"123456\",\n \"customerName\": \"João da Silva\",\n \"email\": \"joao@email.com\",\n \"taxId\": \"123.456.789-01\",\n \"description\": null,\n \"emvQrCode\": null,\n \"paidAt\": \"2024-01-15T10:35:00Z\",\n \"endToEndId\": \"E00000000...\",\n \"createdAt\": \"2024-01-15T10:30:00Z\",\n \"feeInfo\": {\n \"grossAmount\": 100.0,\n \"netAmount\": 99.01,\n \"fees\": {\n \"pix\": 0.99\n }\n },\n \"splits\": null,\n \"customer\": {\n \"customerId\": \"cus_xxx\",\n \"name\": \"João da Silva\"\n },\n \"subscription\": null,\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 \"code\": \"CHARGE_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Cancelar Cobrança", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "DELETE", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "charges", ":chargeId" ], "raw": "{{base_url}}/v1/charges/:chargeId", "variable": [ { "key": "chargeId", "value": "cha_xxx" } ] }, "description": "Cancela uma cobrança que ainda não foi paga, invalidando o Pix ou boleto gerado.\n\n# Cancelar 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 \"message\": \"Cobrança cancelada com sucesso\",\n \"chargeId\": \"cha_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 \"code\": \"CHARGE_NOT_CANCELABLE\",\n \"message\": \"Status não permite cancelamento\"\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 \"code\": \"CHARGE_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Arquivar Cobrança", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "charges", ":chargeId", "archive" ], "raw": "{{base_url}}/v1/charges/:chargeId/archive", "variable": [ { "key": "chargeId", "value": "cha_xxx" } ] }, "description": "Guarda uma cobrança do histórico sem cancelá-la, útil para organizar cobranças antigas.\n\n# Arquivar cobrança\n\nSó cobranças canceladas podem ser arquivadas." }, "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 \"chargeId\": \"cha_xxx\",\n \"status\": \"ARCHIVED\",\n \"archivedAt\": \"2024-01-20T10:00:00Z\"\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 \"code\": \"CHARGE_NOT_ARCHIVABLE\",\n \"message\": \"Só cobranças canceladas podem ser arquivadas\"\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 \"code\": \"CHARGE_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Baixar Boleto", "request": { "auth": { "type": "noauth" }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "charges", ":chargeId", "boleto.pdf" ], "raw": "{{base_url}}/v1/charges/:chargeId/boleto.pdf?download=", "query": [ { "key": "download", "value": "", "description": "1 | true — força download", "disabled": true } ], "variable": [ { "key": "chargeId", "value": "cha_xxx" } ] }, "description": "Retorna o arquivo PDF do boleto para enviar ou exibir ao cliente.\n\n# PDF do boleto (público)\n\nRetorna PDF em base64 com `Content-Type: application/pdf`." }, "response": [ { "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 \"code\": \"CHARGE_NOT_BOLETO\"\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 \"code\": \"BOLETO_PDF_NOT_AVAILABLE\"\n}", "cookie": [] } ] } ] }, { "name": "Checkouts", "item": [ { "name": "Criar Checkout", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "checkouts" ], "raw": "{{base_url}}/v1/checkouts" }, "description": "Cria uma página de pagamento configurável com produtos, formas de pagamento aceitas, cupons e aparência personalizada.\n\n# Criar payment link (oferta)\n\n**Scopes:** `checkouts/write`. Link reutilizável, sem cliente pré-preenchido. Obrigatório `priceId` ou `product`.\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `priceId` | ✅* | string | ID do preço |\n| `product` | ✅* | object | Produto + preços inline (alternativa) |\n| `allowedPaymentMethods` | ✅ | string[] | `pix` `creditcard` `boleto` |\n| `successUrl`/`cancelUrl`/`redirectAfterPaymentUrl` | ❌ | string | URLs |\n| `maxInstallments` | ❌ | number | 1–12 |\n| `freeInstallments` | ❌ | number | 1–12 (default 1) |\n| `passFeesToCustomer` | ❌ | boolean | default false |\n| `primaryColor`/`secondaryColor`/`fontColor` | ❌ | string | hex |\n| `showProductImage` | ❌ | boolean | default true |\n| `orderBumps` | ❌ | array | Produtos adicionais |", "body": { "mode": "raw", "raw": "{\n \"priceId\": \"price_xxx\",\n \"allowedPaymentMethods\": [\n \"pix\",\n \"creditcard\",\n \"boleto\"\n ],\n \"successUrl\": \"https://meusite.com/obrigado\",\n \"cancelUrl\": \"https://meusite.com/cancelado\",\n \"redirectAfterPaymentUrl\": \"https://meusite.com/redirect\",\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 Checkouts", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "checkouts" ], "raw": "{{base_url}}/v1/checkouts?limit=15&lastKey=&status=&search=", "query": [ { "key": "limit", "value": "15", "description": "", "disabled": true }, { "key": "lastKey", "value": "", "description": "base64", "disabled": true }, { "key": "status", "value": "", "description": "", "disabled": true }, { "key": "search", "value": "", "description": "", "disabled": true } ] }, "description": "Lista todas as páginas de pagamento criadas com seus status e configurações.\n\n# Listar checkouts" }, "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 Checkout", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "checkouts", ":id" ], "raw": "{{base_url}}/v1/checkouts/:id", "variable": [ { "key": "id", "value": "pl_xxx" } ] }, "description": "Retorna os detalhes completos de uma página de pagamento, incluindo produtos e formas aceitas.\n\n# Consultar checkout\n\nAceita `cha_*` (charge), `cs*` (sessão), `price_*` (preço), `pl*` (payment link). Auth opcional (público)." }, "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 \"code\": \"CHECKOUT_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Atualizar Checkout", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "checkouts", ":id" ], "raw": "{{base_url}}/v1/checkouts/:id", "variable": [ { "key": "id", "value": "pl_xxx" } ] }, "description": "Atualiza as configurações de uma página de pagamento, como produtos ou formas de pagamento disponíveis.\n\n# Atualizar checkout\n\n| Campo | Obrig. | Tipo |\n|---|---|---|\n| `priceId` | ❌ | string |\n| `discounts` | ❌ | array |\n| `trialDays` | ❌ | number |\n| `maxInstallments` | ❌ | number |\n| `primaryColor`/`secondaryColor`/`fontColor` | ❌ | string (hex) |\n| `showProductImage` | ❌ | boolean |\n| `applyBrandingToAllPrices` | ❌ | boolean |", "body": { "mode": "raw", "raw": "{\n \"priceId\": \"price_yyy\",\n \"discounts\": [],\n \"maxInstallments\": 6,\n \"primaryColor\": \"#FF0000\",\n \"showProductImage\": false,\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 \"code\": \"CHECKOUT_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Checkout Transparente", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "checkouts", "pay" ], "raw": "{{base_url}}/v1/checkouts/pay" }, "description": "Este é o endpoint onde o pagamento é de fato processado. O cliente preenche os dados diretamente na sua página e você envia para cá.\n\n# Efetuar pagamento via checkout transparente\n\nUse esta rota para **concluir uma compra** a partir de uma sessão de checkout já criada. Não precisa de login — qualquer pessoa com o ID da sessão pode pagar.\n\nQuando o pagamento é aprovado, a sessão é marcada como paga e não pode ser usada novamente.\n\n**Autenticação:** não é necessária.\n\n---\n\n## Identificação da sessão (obrigatório — um dos dois)\n\n| Campo | Tipo | Descrição |\n|---|---|---|\n| `sessionId` | texto | ID da sessão criada pelo vendedor. Começa com `cs_` (produção) ou `SANDBOX_cs_` (sandbox) |\n| `checkoutId` | texto | Mesmo que `sessionId` — aceito como alternativa |\n\n---\n\n## Forma de pagamento\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `paymentMethod` | ✅ | texto | Forma de pagamento: `pix`, `creditcard` ou `boleto` |\n\n**Cartão de crédito** — preencha `card` OU `tokenId`:\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `card.number` | ✅* | texto | Número do cartão (13 a 19 dígitos, só números) |\n| `card.cvv` | ✅* | texto | Código de segurança (3 ou 4 dígitos) |\n| `card.name` | ✅* | texto | Nome exatamente como está no cartão |\n| `card.expiration` | ✅* | texto | Validade no formato `MM/YYYY` (ex: `12/2027`) |\n| `paymentMethodId` | ✅* | texto | ID de cartão tokenizado via `/v1/payment-methods/tokenize` — substitui `card` |\n| `tokenId` | ✅* | texto | Token de cartão salvo em pagamento anterior — substitui `card` |\n| `cardInfo.brand` | ❌ | texto | Bandeira do cartão tokenizado (ex: `VISA`) |\n| `cardInfo.maskedNumber` | ❌ | texto | Número mascarado do cartão tokenizado (ex: `411111******1111`) |\n| `cardInfo.holderName` | ❌ | texto | Nome do titular do cartão tokenizado |\n| `cardInfo.expiration` | ❌ | texto | Validade do cartão tokenizado (`MM/YYYY`) |\n\n*Para cartão, preencha `card` com os dados brutos, **ou** `paymentMethodId` com um cartão tokenizado, **ou** `tokenId` com um token salvo.\n\n---\n\n## Dados do comprador\n\nSe a sessão já foi criada com dados do cliente, eles são preenchidos automaticamente. Os campos enviados aqui sobrescrevem os da sessão.\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `customer.name` | ✅ | texto | Nome completo do comprador |\n| `customer.email` | ✅ | texto | E-mail do comprador |\n| `customer.documentNumber` | ✅ | texto | CPF (11 dígitos) ou CNPJ (14 dígitos), somente números |\n| `customer.phone` | ❌ | texto | Telefone no formato internacional (ex: `+5511999998888`) |\n| `customer.cep` | ❌ | texto | CEP com 8 dígitos — necessário para PIX com dados do pagador |\n| `customer.address.street` | ✅ boleto | texto | Rua ou logradouro |\n| `customer.address.number` | ✅ boleto | texto | Número da residência |\n| `customer.address.complement` | ❌ | texto | Complemento (apto, sala, etc.) |\n| `customer.address.neighborhood` | ✅ boleto | texto | Bairro |\n| `customer.address.city` | ✅ boleto | texto | Cidade |\n| `customer.address.state` | ✅ boleto | texto | Estado com 2 letras (ex: `SP`) |\n| `customer.address.zipCode` | ✅ boleto | texto | CEP com 8 dígitos |\n| `customer.address.country` | ❌ | texto | País (padrão `BR`) |\n| `customer.address.cityCode` | ❌ | texto | Código IBGE da cidade — necessário para emissão de nota fiscal |\n| `customer.metadata` | ❌ | objeto | Informações extras do cliente (chave-valor livre) |\n\n*Campos marcados como \"✅ boleto\" são obrigatórios apenas quando `paymentMethod` é `boleto`.\n\n---\n\n## Produto ou valor\n\nSe a sessão já tem produtos configurados, não é necessário enviar. Para alterar ou usar uma cobrança avulsa:\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `items[].priceId` | ✅* | texto | ID do preço do produto (`price_...`) |\n| `items[].quantity` | ❌ | número | Quantidade (padrão: 1) |\n| `items[].isOrderBump` | ❌ | sim/não | Marcar como produto adicional (order bump) |\n| `amount` | ✅* | número | Valor em reais para cobrança avulsa — use quando não há `items` |\n| `description` | ❌ | texto | Descrição da cobrança avulsa |\n\n*Envie `items` com produtos **ou** `amount` com valor avulso — um dos dois é obrigatório.\n\n---\n\n## Parcelamento\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `installments` | ❌ | número | Quantidade de parcelas (1 a 12, padrão 1). Limite por tipo de plano: anual→12, semestral→6, trimestral→3, avulso→12 |\n| `passFeesToCustomer` | ❌ | sim/não | Repassar as taxas da plataforma para o comprador (padrão: não) |\n| `freeInstallments` | ❌ | número | Quantidade de parcelas sem juros (0 a 12, padrão 1) |\n\n---\n\n## Recorrência\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `billingDay` | ❌ | número | Dia do mês em que as cobranças recorrentes serão geradas (1 a 31) |\n| `prorataStartDate` | ❌ | texto | Data de início para cálculo de pró-rata (YYYY-MM-DD) |\n| `recurrencyStartDate` | ❌ | texto | Data de início da recorrência (YYYY-MM-DD, hoje ou futura) |\n\n---\n\n## Boleto\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `dueDate` | ❌ | texto | Data de vencimento do boleto (YYYY-MM-DD, deve ser maior que hoje) |\n| `boletoDueDays` | ❌ | número | Dias até o vencimento a partir de hoje (mínimo 1) — calculado automaticamente se `dueDate` for informado |\n| `expirationAfterDueDate` | ❌ | número | Dias para o boleto ser cancelado após o vencimento (0 a 60) |\n| `boletoInstructions.fine` | ❌ | número | Multa por atraso em porcentagem (0.1 a 100). A soma de `fine + interest` não pode passar de 60% |\n| `boletoInstructions.interest` | ❌ | número | Juros mensais por atraso em porcentagem (0.1 a 100) |\n| `boletoInstructions.discount.amount` | ❌ | número | Valor do desconto para pagamento antecipado |\n| `boletoInstructions.discount.modality` | ❌ | texto | Tipo do desconto: `fixed` (valor em reais) ou `percent` (porcentagem). Padrão: `fixed` |\n| `boletoInstructions.discount.limitDate` | ❌ | texto | Data limite para usar o desconto (YYYY-MM-DD, deve ser antes de `dueDate`) |\n\n---\n\n## PIX com dados do pagador\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `expiration` | ❌ | texto | Data de expiração do QR Code PIX (YYYY-MM-DD, não pode ser passada) |\n\n---\n\n## Cupom e descontos\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `couponCode` | ❌ | texto | Código de cupom de desconto |\n| `discounts` | ❌ | lista | Descontos manuais — sobrescrevem os da sessão. Cada item deve ter `type` (`PERCENTAGE` ou `FIXED`) e `amount` ou `value`. Campos opcionais: `paymentMethod`, `fromCycle`, `toCycle`, `durationMonths` |\n\n---\n\n## Split de pagamento\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `split[].type` | ✅ | texto | Tipo do repasse: `percentage` (porcentagem) ou `fixed` (valor fixo) |\n| `split[].accountNumber` | ❌ | texto | Número da conta que vai receber o repasse |\n| `split[].amount` | ✅ | número | Valor ou porcentagem do repasse |\n\n---\n\n## Outros\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `metadata` | ❌ | objeto | Informações extras (chave-valor livre) que ficam salvas na cobrança |\n| `nfConfigId` | ❌ | texto | ID da configuração de nota fiscal. Quando informado, o endereço do comprador é obrigatório |\n| `dfp_id` | ❌ | texto | ID de device fingerprint — usado para análise antifraude |\n\n---\n\n**Erros comuns:** `404 SESSION_NOT_FOUND` (sessão não existe), `400 SESSION_INACTIVE` (sessão já foi paga ou expirou), `400 INVALID_DATA` (campo inválido), `402` (pagamento recusado pelo banco).", "body": { "mode": "raw", "raw": "{\n \"sessionId\": \"cs_abc123\",\n \"paymentMethod\": \"creditcard\",\n\n \"customer\": {\n \"name\": \"João da Silva\",\n \"email\": \"joao@email.com\",\n \"documentNumber\": \"12345678901\",\n \"phone\": \"+5511999998888\",\n \"cep\": \"01310100\",\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 \"metadata\": { \"origem\": \"site\" }\n },\n\n // Opção 1: cartão tokenizado (recomendado)\n \"paymentMethodId\": \"pm_abc123\",\n\n // Opção 2: dados brutos do cartão\n \"card\": {\n \"number\": \"4111111111111111\",\n \"cvv\": \"123\",\n \"name\": \"JOAO DA SILVA\",\n \"expiration\": \"12/2027\"\n },\n\n \"items\": [\n { \"priceId\": \"price_abc123\", \"quantity\": 1, \"isOrderBump\": false }\n ],\n\n \"installments\": 1,\n \"passFeesToCustomer\": false,\n \"freeInstallments\": 1,\n\n \"billingDay\": 10,\n \"prorataStartDate\": \"2026-06-15\",\n \"recurrencyStartDate\": \"2026-07-01\",\n\n \"dueDate\": \"2026-07-30\",\n \"boletoDueDays\": 7,\n \"expirationAfterDueDate\": 30,\n\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\n \"expiration\": \"2026-07-30\",\n\n \"couponCode\": \"PROMO10\",\n\n \"discounts\": [\n {\n \"type\": \"PERCENTAGE\",\n \"value\": 10,\n \"paymentMethod\": \"pix\",\n \"fromCycle\": 1,\n \"toCycle\": 3,\n \"durationMonths\": 3\n }\n ],\n\n \"split\": [\n {\n \"type\": \"percentage\",\n \"accountNumber\": \"123456\",\n \"amount\": 10\n }\n ],\n\n \"metadata\": { \"referencia\": \"pedido-001\" },\n \"nfConfigId\": null,\n \"dfp_id\": null\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 assinatura 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 \"subscriptionId\": \"sub_xxx\",\n \"customerId\": \"cus_xxx\",\n \"chargeId\": \"cha_xxx\"\n}", "cookie": [] }, { "name": "200 cobrança avulsa (cha_)", "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 \"chargeId\": \"cha_abc123\",\n \"status\": \"paid\"\n}", "cookie": [] }, { "name": "200 assinatura 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 \"subscriptionId\": \"sub_xxx\",\n \"pix\": {\n \"emv\": \"...\",\n \"qrCode\": \"...\"\n }\n}", "cookie": [] }, { "name": "200 assinatura boleto", "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 \"subscriptionId\": \"sub_xxx\",\n \"boleto\": {\n \"digitableLine\": \"...\",\n \"dueDate\": \"2024-02-15\"\n }\n}", "cookie": [] }, { "name": "402", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "Payment Required", "code": 402, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"status\": \"failed\",\n \"error\": \"Cartão recusado\"\n}", "cookie": [] }, { "name": "404 SESSION_NOT_FOUND", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"SESSION_NOT_FOUND\"\n}", "cookie": [] }, { "name": "404 CHARGE_NOT_FOUND", "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\": \"CHARGE_NOT_FOUND\"\n }\n}", "cookie": [] }, { "name": "400 CHARGE_NOT_PAYABLE", "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\": \"Apenas cobranças pendentes podem ser processadas\",\n \"code\": \"CHARGE_NOT_PAYABLE\"\n }\n}", "cookie": [] }, { "name": "400 MISSING_CARD_DATA", "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\": \"tokenId, card ou paymentMethodId é obrigatório\",\n \"code\": \"MISSING_CARD_DATA\"\n }\n}", "cookie": [] } ] }, { "name": "Criar Sessão de Checkout", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "checkout-sessions" ], "raw": "{{base_url}}/v1/checkout-sessions" }, "description": "Cria um acesso temporário e seguro a uma página de pagamento, com validade e uso único.\n\n# POST /v1/checkout-sessions — Criar Sessão de Checkout\n\n**Auth:** Bearer (Cognito) ou M2M (`checkouts/write`)\n\nCria um link de pagamento nominal com cliente e configurações pré-preenchidas. Uso único — expira após o pagamento.\n\n## Resposta\n\n```json\n{\n \"id\": \"cs_abc123\",\n \"url\": \"https://app.validapay.com.br/pagamento/cs_abc123\",\n \"priceId\": \"price_abc123\"\n}\n```\n\n## Referência dos campos\n\n| Campo | Obrig. | Tipo | Descrição |\n|-------|--------|------|------------|\n| `priceId` | ✅ | `string` | Deve começar com `price_`. Deve pertencer à conta autenticada |\n| `allowedPaymentMethods` | — | `string[]` | Métodos exibidos: `pix` `creditcard` `boleto`. Omitir = usa padrão do price |\n| `customer.name` | — | `string` | Pré-preenche o nome no checkout |\n| `customer.email` | — | `string` | Usado para localizar cliente existente pelo `documentNumber` |\n| `customer.documentNumber` | — | `string` | CPF (11) ou CNPJ (14 dígitos) |\n| `customer.phone` | — | `string` | Telefone |\n| `customer.address` | — | `object` | Endereço completo. Obrigatório para boleto no momento do pagamento |\n| `customer.address.type` | — | `string` | Tipo do endereço (ex: `BILLING`) |\n| `customer.address.cityCode` | — | `string` | Código IBGE — obrigatório para emissão de nota fiscal |\n| `items` | — | `array` | Lista de `{ priceId, quantity }`. Sobrescreve o item principal para multi-produto |\n| `billingDay` | — | `number` | 1–31. Dia do mês para cobranças recorrentes |\n| `prorataStartDate` | — | `string` | `YYYY-MM-DD`. Data de início para cálculo de prorata |\n| `installments` | — | `number` | 1–12. Parcelas fixas para a sessão |\n| `dueDate` | — | `string` | `YYYY-MM-DD` (deve ser maior que hoje). Deriva `boletoDueDays` automaticamente |\n| `boletoDueDays` | — | `number` | Dias para vencimento do boleto (mín. 1). Ignorado se `dueDate` for informado |\n| `expirationAfterDueDate` | — | `number` | 0–60. Dias após vencimento que o boleto ainda aceita pagamento |\n| `discounts` | — | `array` | Descontos aplicados à sessão. Cada item: `{ type, value, paymentMethod?, fromCycle?, toCycle?, durationMonths? }` |\n| `discounts[].type` | — | `string` | `PERCENTAGE` ou `FIXED` |\n| `discounts[].value` | — | `number` | Valor do desconto |\n| `discounts[].paymentMethod` | — | `string` | Restringir a um método: `pix` `creditcard` `boleto` |\n| `discounts[].fromCycle` | — | `number` | Ciclo inicial de aplicação |\n| `discounts[].toCycle` | — | `number` | Ciclo final de aplicação |\n| `discounts[].durationMonths` | — | `number` | Duração em meses |\n| `passFeesToCustomer` | — | `boolean` | Repassa taxas ao cliente. Default `false` |\n| `freeInstallments` | — | `number` | 1–12. Parcelas sem juros. Default `1` |\n| `maxInstallments` | — | `number` | 1–12. Limite máximo de parcelas exibido |\n| `boletoInstructions.fine` | — | `number` | Multa em % (0.1–100). `fine + interest` ≤ 60% |\n| `boletoInstructions.interest` | — | `number` | Juros mensais em % (0.1–100) |\n| `boletoInstructions.discount.amount` | — | `number` | Valor do desconto antecipado |\n| `boletoInstructions.discount.modality` | — | `string` | `fixed` (R$) ou `percent` (%) |\n| `boletoInstructions.discount.limitDate` | — | `string` | `YYYY-MM-DD` — deve ser anterior ao `dueDate` |\n| `orderBumps` | — | `array` | Produtos adicionais exibidos no checkout |\n| `orderBumps[].priceId` | ✅ | `string` | priceId do produto adicional |\n| `orderBumps[].callToAction` | — | `string` | Texto do botão de adicionar |\n| `orderBumps[].title` | — | `string` | Título exibido |\n| `orderBumps[].description` | — | `string` | Descrição exibida |\n| `orderBumps[].showImage` | — | `boolean` | Exibir imagem do produto |\n| `primaryColor` | — | `string` | Cor primária (hex) |\n| `secondaryColor` | — | `string` | Cor secundária (hex) |\n| `fontColor` | — | `string` | Cor do texto (hex) |\n| `companyName` | — | `string` | Nome da empresa exibido no checkout |\n| `successUrl` | — | `string` | Redireciona após pagamento aprovado |\n| `failureUrl` | — | `string` | Redireciona após pagamento recusado |\n| `metadata` | — | `object` | Dados livres persistidos na sessão |", "body": { "mode": "raw", "raw": "{\n \"priceId\": \"price_abc123\",\n\n \"allowedPaymentMethods\": [\"pix\", \"creditcard\", \"boleto\"],\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\n \"items\": [\n { \"priceId\": \"price_abc123\", \"quantity\": 1 }\n ],\n\n \"billingDay\": 15,\n \"prorataStartDate\": \"2026-06-11\",\n \"installments\": 1,\n\n \"dueDate\": \"2026-07-30\",\n \"boletoDueDays\": 7,\n \"expirationAfterDueDate\": 30,\n\n \"discounts\": [\n {\n \"type\": \"PERCENTAGE\",\n \"value\": 10,\n \"paymentMethod\": \"pix\",\n \"fromCycle\": 1,\n \"toCycle\": 3,\n \"durationMonths\": 3\n }\n ],\n\n \"passFeesToCustomer\": false,\n \"freeInstallments\": 1,\n \"maxInstallments\": 12,\n\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\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\n \"primaryColor\": \"#6366f1\",\n \"secondaryColor\": \"#818cf8\",\n \"fontColor\": \"#ffffff\",\n \"companyName\": \"Minha Empresa\",\n\n \"successUrl\": \"https://meusite.com/sucesso\",\n \"failureUrl\": \"https://meusite.com/falha\",\n\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 \"code\": \"FORBIDDEN\",\n \"message\": \"Você não tem permissão para usar este produto\"\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 \"code\": \"PRICE_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Buscar Sessão de Checkout", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "checkout-sessions", ":id" ], "raw": "{{base_url}}/v1/checkout-sessions/:id", "variable": [ { "key": "id", "value": "cs_xxx" } ] }, "description": "Retorna os dados de um acesso temporário ativo, como produtos disponíveis e formas de pagamento.\n\n# Consultar sessão de checkout" }, "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 \"code\": \"SESSION_NOT_FOUND\"\n}", "cookie": [] } ] } ] }, { "name": "Assinaturas", "item": [ { "name": "Listar Assinaturas", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions" ], "raw": "{{base_url}}/v1/subscriptions?limit=15&lastKey=&startDate=&endDate=&status=&search=&document=&paymentMethod=&priceId=&productId=", "query": [ { "key": "limit", "value": "15", "description": "", "disabled": true }, { "key": "lastKey", "value": "", "description": "base64", "disabled": true }, { "key": "startDate", "value": "", "description": "YYYY-MM-DD", "disabled": true }, { "key": "endDate", "value": "", "description": "YYYY-MM-DD", "disabled": true }, { "key": "status", "value": "", "description": "ACTIVE|TRIALING|PAST_DUE|PAUSED|CANCELED", "disabled": true }, { "key": "search", "value": "", "description": "nome/doc", "disabled": true }, { "key": "document", "value": "", "description": "CPF/CNPJ", "disabled": true }, { "key": "paymentMethod", "value": "", "description": "CREDIT_CARD|PIX|BOLETO", "disabled": true }, { "key": "priceId", "value": "", "description": "", "disabled": true }, { "key": "productId", "value": "", "description": "", "disabled": true } ] }, "description": "Lista todas as assinaturas com filtros por status, cliente e plano.\n\n# Listar assinaturas\n\n**Scopes:** `subscriptions/read`" }, "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": { "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", ":subscriptionId" ], "raw": "{{base_url}}/v1/subscriptions/:subscriptionId", "variable": [ { "key": "subscriptionId", "value": "sub_xxx" } ] }, "description": "Retorna os detalhes completos de uma assinatura, incluindo o ciclo atual, a data da próxima cobrança e o histórico de pagamentos.\n\n# Consultar assinatura\n\nRetorna `customer`, `items`, `upgrades`, `billingCycles`, `coupon`." }, "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 \"code\": \"SUBSCRIPTION_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Atualizar Assinatura", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", ":subscriptionId" ], "raw": "{{base_url}}/v1/subscriptions/:subscriptionId", "variable": [ { "key": "subscriptionId", "value": "sub_xxx" } ] }, "description": "Altera informações de uma assinatura ativa, como o plano contratado ou o dia de cobrança, sem precisar cancelar e recriar.\n\n# Atualizar assinatura (genérico)\n\nComportamento depende dos campos enviados. Este request cancela.\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `action` | ❌ | string | `cancel` |\n| `reason` | ❌ | string | Motivo |\n| `old.itemId` | ❌ | string | Item a alterar (upgrade/downgrade) |\n| `new.priceId` | ❌ | string | Novo preço |\n| `new.quantity` | ❌ | number | Nova quantidade |", "body": { "mode": "raw", "raw": "{\n \"action\": \"cancel\",\n \"reason\": \"Cliente solicitou cancelamento\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 cancel", "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\": \"CANCELED\",\n \"reason\": \"Cliente solicitou cancelamento\"\n}", "cookie": [] }, { "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\": 45.0\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}", "cookie": [] } ] }, { "name": "Atualizar Assinatura (Item)", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", ":subscriptionId" ], "raw": "{{base_url}}/v1/subscriptions/:subscriptionId", "variable": [ { "key": "subscriptionId", "value": "sub_xxx" } ] }, "description": "Altera informações de um item dentro de uma assinatura ativa.\n\n# Atualizar assinatura — upgrade/downgrade de item\n\nVer descrição do request de cancelamento para a tabela de campos.", "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}", "cookie": [] } ] }, { "name": "Cancelar Assinatura", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", ":subscriptionId" ], "raw": "{{base_url}}/v1/subscriptions/:subscriptionId", "variable": [ { "key": "subscriptionId", "value": "sub_xxx" } ] }, "description": "Cancela uma assinatura, interrompendo todas as cobranças futuras.\n\n# Cancelar assinatura\n\n| Campo | Obrig. | Tipo |\n|---|---|---|\n| `reason` | ❌ | string |", "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 \"code\": \"SUBSCRIPTION_ALREADY_CANCELED\"\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 \"code\": \"SUBSCRIPTION_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Adicionar Item", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", ":subscriptionId", "items" ], "raw": "{{base_url}}/v1/subscriptions/:subscriptionId/items", "variable": [ { "key": "subscriptionId", "value": "sub_xxx" } ] }, "description": "Adiciona um novo produto ou serviço a uma assinatura já existente.\n\n# Adicionar item à assinatura\n\n| Campo | Obrig. | Tipo | Descrição |\n|---|---|---|---|\n| `priceId` | ✅ | string | Preço do item |\n| `quantity` | ❌ | number | ≥ 1 (default 1) |\n| `type` | ❌ | string | `RECURRING` `ONE_TIME` (default RECURRING) |\n| `boletoInstructions` | ❌ | object | Para assinaturas boleto |\n| `expirationAfterDueDate` | ❌ | number | 0–60 |", "body": { "mode": "raw", "raw": "{\n \"priceId\": \"price_xxx\",\n \"quantity\": 1,\n \"type\": \"RECURRING\",\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": "402", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "Payment Required", "code": 402, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"PAYMENT_DECLINED\",\n \"error\": \"Cartão recusado\"\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 \"code\": \"SUBSCRIPTION_NOT_ACTIVE\"\n}", "cookie": [] } ] }, { "name": "Atualizar Item", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", ":subscriptionId", "items", ":itemId" ], "raw": "{{base_url}}/v1/subscriptions/:subscriptionId/items/:itemId", "variable": [ { "key": "subscriptionId", "value": "sub_xxx" }, { "key": "itemId", "value": "item_xxx" } ] }, "description": "Atualiza a quantidade ou o preço de um item dentro de uma assinatura ativa.\n\n# Upgrade/downgrade de item\n\n`:id` = subscriptionId, `:itemId` = ID do item. Pelo menos `priceId` ou `quantity`.\n\n| Campo | Obrig. | Tipo |\n|---|---|---|\n| `priceId` | ✅* | string |\n| `quantity` | ✅* | number |\n| `boletoInstructions` | ❌ | object |\n| `expirationAfterDueDate` | ❌ | number |", "body": { "mode": "raw", "raw": "{\n \"priceId\": \"price_yyy\",\n \"quantity\": 2,\n \"boletoInstructions\": null,\n \"expirationAfterDueDate\": null\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": "402", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "" } }, "status": "Payment Required", "code": 402, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"code\": \"PAYMENT_DECLINED\"\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 \"code\": \"ITEM_NOT_FOUND\"\n}", "cookie": [] } ] }, { "name": "Cobrar Proporcional", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", ":subscriptionId", "prorata" ], "raw": "{{base_url}}/v1/subscriptions/:subscriptionId/prorata", "variable": [ { "key": "subscriptionId", "value": "sub_xxx" } ] }, "description": "Gera uma cobrança pelo valor proporcional ao período já utilizado no mês, útil quando o cliente muda de plano no meio do ciclo.\n\n# Calcular pró-rata (sem cobrar)\n\n| Campo | Obrig. | Tipo |\n|---|---|---|\n| `old.priceId` | ✅ | string |\n| `old.quantity` | ❌ | number |\n| `new.priceId` | ✅ | string |\n| `new.quantity` | ❌ | number |", "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 \"code\": \"OLD_PRICE_NOT_FOUND\"\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 \"code\": \"NEW_PRICE_NOT_FOUND\"\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 \"code\": \"SUBSCRIPTION_NOT_FOUND\"\n}", "cookie": [] } ] } ] } ] }