# SuyPay: documentação completa Gerado de https://docs.suypay.com para assistentes de IA. Índice: https://docs.suypay.com/llms.txt --- # Como a SuyPay funciona A SuyPay fica entre o seu negócio e as contas onde você recebe. Você cria a cobrança na SuyPay, e ela cuida do resto. ## O caminho de uma venda 1. Você cria uma cobrança: pelo painel (e manda o link para o cliente) ou pelo seu sistema. 2. A SuyPay olha as suas **regras** e as contas conectadas e escolhe a melhor para essa venda. 3. Se essa conta estiver fora do ar, a venda passa pela próxima, na hora. 4. Quando o cliente paga, a conta avisa a SuyPay, e a SuyPay avisa você, sempre do mesmo jeito. 5. Todo dia, a SuyPay confere cada venda com a conta e corrige o que estiver diferente. ## O dinheiro é seu O dinheiro cai **direto na sua conta** do Mercado Pago, Asaas, Efí ou Stripe. A SuyPay nunca guarda nem repassa valores. ## Teste e Real O painel tem dois modos, e o seletor fica sempre no topo: | Modo | Para quê | |---|---| | **Teste** | Experimentar à vontade. Usa contas de teste e nada é cobrado de verdade | | **Real** | Vender. Usa as suas contas de verdade | Cada modo tem as próprias contas, cobranças e chaves. Eles nunca se misturam. ## Situação de uma cobrança | Situação | O que quer dizer | |---|---| | Em aberto | Esperando o cliente pagar o Pix ou o boleto | | Processando | A conta está analisando | | Pago | Dinheiro recebido | | Recusado | O banco recusou, ou nenhuma conta conseguiu processar | | Cancelado | Venceu ou foi cancelado | | Devolvido | O dinheiro voltou para o cliente, todo ou em parte | --- # Comece em 5 minutos Vamos fazer uma venda de teste do começo ao fim. Nada aqui movimenta dinheiro de verdade. ## 1. Entre no painel Acesse o [painel](https://docs.suypay.com/app.md) e entre com a sua conta do GitHub. Sua empresa é criada na hora. ## 2. Conecte a conta de teste Vá em **Contas conectadas → Conectar conta → Conta de teste**. Ela não pede cadastro nenhum. > **Dica:** conecte **duas** contas de teste com taxas diferentes. Assim você vê a SuyPay escolhendo a mais barata. ## 3. Crie uma cobrança Clique em **Nova cobrança**, escolha **Pix**, coloque um valor e o nome do cliente. Pronto: o Pix copia e cola já aparece na tela. ## 4. Finja que o cliente pagou Na página da cobrança, clique em **Simular pagamento**. A situação muda para **Pago** e o valor entra no resumo do Início. ## 5. Ligue no seu sistema (opcional) Crie uma chave em **Desenvolvedores → Chaves e MCP** e faça a mesma cobrança por código: ```bash curl https://api.suypay.com/v1/payments \ -H "Authorization: Bearer suy_test_..." \ -H "Content-Type: application/json" \ -d '{ "method": "pix", "amount": 1990, "customer": { "name": "Maria Silva" } }' ``` A resposta traz o Pix em `next_action.qr_code`. Os valores são sempre em **centavos**: `1990` é R$ 19,90. ## Quando quiser vender de verdade Troque o painel para **Real**, conecte a sua conta (Mercado Pago, Asaas, Efí ou Stripe) e crie uma chave real. O resto continua igual. --- # Modo de teste No modo de teste você pode errar à vontade: nenhuma cobrança é de verdade. ## A conta de teste É uma conta que já vem pronta na SuyPay, sem cadastro. Ela se comporta como uma conta de verdade e ainda permite simular problemas. | Se o valor terminar em | Acontece | |---|---| | **,99** (ex.: R$ 50,99) | A conta finge estar fora do ar, e a SuyPay tenta a próxima | | **,13**, só no cartão | O cartão é recusado | | qualquer outro | Dá certo | ## Simular pagamento Pix e boleto da conta de teste da SuyPay ficam **em aberto** até você clicar em **Simular pagamento** no link da cobrança ou na página dela. No Asaas sandbox, o mesmo botão usa o endpoint de confirmação do próprio Asaas e consulta o resultado. Use somente o link ou uma chave de teste: ```bash curl -X POST https://api.suypay.com/v1/payments/pay_.../simulate \ -H "Authorization: Bearer suy_test_..." ``` Nos demais provedores, confirme pelo fluxo de teste da própria conta. A SuyPay só mostra como pago depois que o provedor confirma; o botão não aparece quando a integração não tem confirmação pela API. Nunca use o QR Code ou boleto de teste em um banco real. | Provedor | Como testar a confirmação | |---|---| | [Asaas](https://docs.asaas.com/reference/confirmar-pagamento) | Botão da SuyPay ou API de confirmação do sandbox. | | [Woovi](https://developers.openpix.com.br/docs/test-environment/test-account/test-pay-pix) | Simule no detalhe da cobrança na Woovi ou use o fluxo de teste documentado por ela. | | [Stripe](https://docs.stripe.com/testing) | Use os cartões e métodos de teste com chaves de teste. | | [Mercado Pago](https://www.mercadopago.com.br/developers/pt/docs/checkout-api-payments/integration-test/make-test-purchase) | Faça uma compra com credenciais e dados de teste. | | [Appmax](https://docs.appmax.com.br/guides/webhooks) | Pix e boleto no sandbox são aprovados automaticamente; para cartão, use os cartões de teste da [Appmax](https://docs.appmax.com.br/api-reference/payments/cartao-credito). | | [Efí](https://dev.efipay.com.br/docs/api-pix/cobrancas-imediatas/) | No sandbox Pix, valores até R$ 10,00 são confirmados automaticamente. | ## Ver a troca de conta acontecendo 1. Conecte duas contas de teste. 2. Na primeira, coloque **Simular falhas = 1**: ela sempre vai falhar. 3. Crie uma cobrança. Na página dela, em **Por onde passou**, você vê a primeira conta falhar e a segunda aceitar. 4. Depois de três falhas seguidas, a SuyPay pausa a primeira por um minuto e para de tentar nela. --- # Criar cobranças Pix, boleto ou cartão, sempre do mesmo jeito: `POST /v1/payments`. ## Pix ```json { "method": "pix", "amount": 4990, "customer": { "name": "Maria Silva" } } ``` Mostre para o cliente o `next_action.qr_code` (copia e cola). Quando a conta manda a imagem do QR Code, ela vem em `next_action.qr_code_base64`. Em `next_action.qr_code_url` fica a imagem do QR Code num endereço público, pronta para um e-mail, um chat ou um [bot do Discord](https://docs.suypay.com/bots.md). ## Boleto O boleto precisa do CPF ou CNPJ e do endereço do cliente: ```json { "method": "boleto", "amount": 15900, "customer": { "name": "Carlos Souza", "email": "carlos@email.com", "document": "11144477735", "address": { "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "zip": "01310100" } } } ``` O boleto vem em `next_action` sempre com os dois números, seja qual for a conta: `digitable_line` (a linha digitável formatada, `34191.79001 01043.510047 91020.150008 1 93460000026035`) e `barcode` (os 44 dígitos do código de barras). Algumas contas só mandam um deles; a SuyPay calcula o outro. Também vêm `url` (a página do boleto), `pdf` quando a conta tem e `due_date`. A página de pagamento desenha o código de barras para o app do banco ler pela câmera, mostra a linha para copiar e o PDF para baixar. ## Cartão O jeito recomendado é o [cartão salvo](https://docs.suypay.com/cards.md). O cliente digita o cartão nos campos da SuyPay, você salva e cobra com `card.id`. Esse cartão serve em **qualquer** conta conectada que aceite cartão salvo, com troca automática de conta se uma falhar, e também em [assinaturas](https://docs.suypay.com/card-subscriptions.md): ```json { "method": "card", "amount": 25000, "card": { "id": "card_4Fh...", "installments": 3 }, "customer": { "name": "Ana Lima", "document": "12345678909" } } ``` Também dá para usar o formulário de cartão **da própria conta** (Stripe, Efí e outras) e mandar só o token dela: ```json { "method": "card", "amount": 25000, "card": { "token": "tok_...", "installments": 3 }, "customer": { "name": "Ana Lima", "document": "12345678909" } } ``` > **Dica:** o token de uma conta só funciona na conta que o gerou. Com ele, crie uma [regra](https://docs.suypay.com/rules.md) que mande cartão sempre para essa conta, ou passe a usar o cartão salvo. Em nenhum dos dois casos o número do cartão passa pelo seu site ou pela SuyPay. ## Todos os campos | Campo | | | |---|---|---| | `method` | `pix`, `boleto` ou `card` | opcional: omita para o cliente escolher no link | | `amount` | valor em centavos | obrigatório | | `customer.name` | nome do cliente | obrigatório | | `customer.document` | CPF ou CNPJ | boleto, cartão, Asaas e Efí | | `customer.email` | e-mail | recomendado | | `customer.address` | endereço | boleto | | `customer.ip` | IP de quem está comprando | se não mandar, a SuyPay usa o IP de quem chamou a API | | `description` | o que aparece para você | | | `expires_in_minutes` | prazo do Pix ou, sem `method`, prazo para o cliente escolher no link | | | `metadata` | informações suas (`{ "pedido": "1042" }`) | usado nas regras e copiado para a conta | | `tracking` | UTMs e clique do anúncio (`utm_source`, `utm_campaign`, `fbclid`...) | vai para as [integrações](https://docs.suypay.com/integrations.md) | ## IP do comprador Asaas, Appmax e Mercado Pago usam o IP de quem compra para barrar fraude no cartão. Se você cria a cobrança do seu servidor, mande o IP do cliente em `customer.ip`. Sem ele, a SuyPay usa o IP de quem chamou a API, que nesse caso é o do seu servidor. ```json "customer": { "name": "Ana Lima", "document": "12345678909", "ip": "177.12.34.56" } ``` ## Metadata Até 50 chaves, cada uma com até 40 letras, e valores em texto de até 500 letras. A SuyPay guarda tudo na cobrança, usa nas [regras](https://docs.suypay.com/rules.md) e copia para a conta quando ela tem onde guardar: | Conta | Onde aparece | |---|---| | Stripe | `metadata` do pagamento | | Mercado Pago | `metadata` do pagamento | | Efí (Pix) | informações adicionais do Pix | | Woovi | informações adicionais da cobrança | | Asaas, Appmax | não têm onde guardar (fica só na SuyPay) | ## Sem cobrança em dobro Mande o cabeçalho `Idempotency-Key` com um código único do pedido. Se a mesma chamada for repetida, por exemplo numa falha de internet, a SuyPay devolve a mesma cobrança em vez de criar outra. ```bash -H "Idempotency-Key: pedido-1042" ``` --- # Link de pagamento Toda cobrança tem uma página para o cliente pagar e acompanhar a situação, que **atualiza sozinha**. Se você não escolher uma forma ao criar, o cliente escolhe entre as disponíveis nas suas contas. No Pix, a página mostra o QR Code e o botão de copiar. No boleto, mostra a linha digitável e o arquivo quando disponíveis. Para cartão pela Stripe, abre o Checkout seguro da Stripe e volta à página da SuyPay com o resultado. É o jeito mais rápido de cobrar sem site: crie a cobrança no painel e mande o link pelo WhatsApp. ## Onde pegar - **No painel:** escolha **O cliente, pelo link** e crie a cobrança. O link vai para a área de transferência e fica na página da cobrança. - **Na API:** omita `method` ao criar a cobrança; o campo `payment_url` vem na resposta. ```json { "id": "pay_3kXy...", "status": "requires_method", "payment_url": "https://checkout.SEU-DOMINIO/pay_3kXy...?t=Qm9..." } ``` ## O que o cliente vê - O nome da sua empresa e a descrição da cobrança. - As formas disponíveis e, depois da escolha, o QR Code, a linha do boleto ou o botão para abrir o checkout seguro do cartão. - Quanto tempo o Pix ainda vale. - O código de barras do boleto, para o app do banco ler pela câmera, junto da linha digitável. - **Pagamento confirmado** assim que a conta confirmar, e o **comprovante** saindo de uma maquininha: valor, data e hora, forma, quem pagou (CPF mascarado), o identificador do Pix e um código de autenticação com QR Code para conferir. O cliente baixa em PDF ou compartilha. Quem abrir o link depois de pago vê o comprovante já impresso. Para cartão escolhido pelo cliente, a Stripe coleta os dados no Checkout dela. Apple Pay e Google Pay podem aparecer ali quando a Stripe considerar a carteira elegível para a conta, dispositivo e navegador. Cobranças de cartão criadas diretamente pela API continuam usando token da conta. A página da SuyPay não recebe número ou código de segurança do cartão. A página não mostra dados do cliente nem qual conta recebeu. O link tem um código que não dá para adivinhar: só quem recebeu o link consegue abrir. Os links novos da página da SuyPay usam `checkout.SEU-DOMINIO/`. Os links antigos em `pay.SEU-DOMINIO/` e `/pay/` continuam abrindo. O subdomínio precisa estar ligado ao mesmo projeto da SuyPay; em testes locais, use `checkout.localhost:5173`. ## Página da própria conta A página da SuyPay é igual para todo mundo: não dá para mudar cores, logo ou textos. Se você quer uma página com a sua marca, use a da própria conta. Asaas, Mercado Pago, Stripe, Woovi e Efí Bank (boleto) têm uma, e você personaliza no painel delas. Para usar, abra a conta em **Contas conectadas › Editar** e, em **Página de pagamento**, escolha **Da própria conta**. A partir daí, o `payment_url` das cobranças de Pix e boleto que passarem por essa conta aponta para a página dela. A SuyPay continua acompanhando o pagamento do mesmo jeito. Cartão continua na página da SuyPay para mostrar a situação e eventual confirmação bancária. Pela API, mande `"checkout": "provider"` ao conectar ou editar a conta (`"suypay"` volta para a página da SuyPay). Cobranças já criadas não mudam. Se a conta não devolver uma página para alguma cobrança (o Pix da Efí, por exemplo), o link continua sendo o da SuyPay. ## Cartão recusado Uma tentativa recusada não estraga o link. Se o banco recusar o cartão, ou se nenhuma conta conseguir gerar o Pix naquele momento, a página volta para **Escolha como pagar** com o motivo em linguagem simples (por exemplo, "O banco não aprovou o cartão. Tente outro cartão ou pague com Pix.") e o cliente tenta de novo ali mesmo. - A cobrança fica em `requires_method`, com `failure_code` e `last_error` da última tentativa. Cada tentativa fica registrada na cobrança. - Você recebe `payment.attempt_failed`, não `payment.failed`: o link continua valendo. - Depois de 3 cartões recusados no mesmo link, cartão deixa de ser aceito nele (proteção contra teste de cartões). Veja [Proteção](https://docs.suypay.com/protection.md). ## No seu site Para o cliente pagar sem sair do seu site, carregue o `checkout.js` e abra o `payment_url` por cima da página. Veja [Checkout no seu site](https://docs.suypay.com/checkout-embed.md). --- # Checkout no seu site O `checkout.js` abre a página de pagamento da SuyPay por cima do seu site, numa janela (no computador) ou numa folha que sobe da parte de baixo (no celular). O cliente escolhe a forma, paga e volta para a sua página, sem trocar de endereço. Funciona com qualquer cobrança que tenha `payment_url`: crie a cobrança no seu servidor e passe o link para o navegador. ## Sem código ```html ``` Qualquer elemento com `data-suypay-checkout` abre o pagamento ao ser clicado. ## Com código ```js const pagamento = SuyPay.checkout({ url: cobranca.payment_url, onSuccess: ({ id, status }) => { // o comprador viu "Pagamento confirmado". Libere o pedido quando o webhook chegar. location.href = '/obrigado?pedido=' + id }, onStatus: ({ status }) => console.log('agora:', status), onClose: ({ status }) => { /* fechou: status é o último que a página mostrou */ }, }) // pagamento.close() fecha por código ``` | Opção | Para quê | |---|---| | `url` | o `payment_url` da cobrança (obrigatório) | | `onSuccess` | quando a cobrança é paga | | `onStatus` | a cada mudança: `requires_method`, `processing`, `pending`, `succeeded`... | | `onClose` | quando o cliente fecha (botão, tecla Esc ou clique fora) | | `closeOnSuccess` | `false` mantém a janela aberta depois do pagamento. Por padrão ela fecha sozinha 2,6 s depois da confirmação | ## O que vale como pago Os avisos do `checkout.js` vêm do navegador do cliente: use-os para a tela, nunca para liberar o produto. Quem confirma é o [webhook](https://docs.suypay.com/webhooks.md) `payment.succeeded`, assinado pela SuyPay, ou um `GET /v1/payments/{id}` no seu servidor. ## UTMs Com o [`utm.js`](https://docs.suypay.com/integrations.md) no mesmo site, as UTMs da visita vão junto para o pagamento, como num link comum. --- # Cartão salvo O cartão é digitado **uma vez**, nos campos de cartão da SuyPay, e vira um `card_…`. A partir daí, **qualquer conta conectada** que aceite cartão salvo cobra esse cartão, inclusive em [assinaturas](https://docs.suypay.com/card-subscriptions.md). Se uma conta cair, a cobrança passa para a próxima, como no Pix e no boleto. O número do cartão **não passa pelo seu site nem pela SuyPay**. Ele é digitado num quadro do cofre de cartões da SuyPay, fica guardado lá criptografado e só sai no momento da cobrança, direto para a conta. Com isso, seu site fica no nível mais simples do PCI DSS (SAQ A). Como o cofre protege o cartão está em [Segurança](https://docs.suypay.com/security.md). ## 1. Mostre os campos de cartão Peça a configuração do modo em que você está (o `publishable_key` pode ir para o navegador): ```bash curl https://api.suypay.com/v1/cards/config -H "Authorization: Bearer suy_test_..." ``` ```json { "vault": { "script": "https://vault.../elements/v1/suy.js", "publishable_key": "pk_test_..." } } ``` No seu checkout: ```html
``` Quem digita é o cliente: os campos de número, validade e CVV ficam dentro do quadro, e o seu código recebe só o `tok_…`. Para combinar com o seu site, passe `style` com `text`, `muted`, `border`, `focus`, `error`, `bg` (cores), `radius`, `size` e `font`. ### Só nos seus sites Por padrão, qualquer site consegue mostrar os campos com a sua chave pública. Diga quais são os seus, e o cofre recusa o quadro e os tokens vindos de qualquer outro (ele trava o quadro com `frame-ancestors` e confere a origem de cada token): ```bash curl -X PATCH https://api.suypay.com/v1/cards/config \ -H "Authorization: Bearer suy_test_..." \ -H "Content-Type: application/json" \ -d '{ "allowed_origins": ["https://loja.com.br", "https://www.loja.com.br"] }' ``` Use só o começo do endereço, com `https://` (no modo de teste, `http://localhost` também vale). A página de pagamento da SuyPay entra sozinha na lista, para os links continuarem funcionando. Uma lista vazia volta a liberar qualquer site. No painel, fica em **Chaves e MCP → Campos de cartão**. ## 2. Salve o cartão Do seu servidor, em até 24 horas: ```bash curl https://api.suypay.com/v1/cards \ -H "Authorization: Bearer suy_test_..." \ -H "Content-Type: application/json" \ -d '{ "vault_token": "tok_...", "holder_name": "ANA LIMA", "customer": { "name": "Ana Lima", "document": "52998224725" } }' ``` ```json { "id": "card_4Fh...", "object": "card", "brand": "visa", "last4": "1111", "exp_month": 12, "exp_year": 2030, "holder_name": "ANA LIMA", "fingerprint": "Xk2...", "cvc_available_until": "2026-10-19T18:30:00.000Z" } ``` O `fingerprint` é igual para o mesmo número de cartão, mesmo em clientes diferentes. Use para achar cartões repetidos. ## 3. Cobre ```json { "method": "card", "amount": 25000, "card": { "id": "card_4Fh...", "installments": 3 }, "customer": { "name": "Ana Lima", "document": "52998224725", "email": "ana@exemplo.com" } } ``` Cobrar cartão salvo exige uma chave **completa**: uma chave restrita só de cobranças não cobra cartão salvo, porque isso cobra o cliente sem ele estar presente. ## CVV O CVV fica guardado só até a **primeira aprovação** e no máximo **1 hora**. É a regra do PCI DSS. O campo `cvc_available_until` diz até quando ele existe. - Algumas contas pedem o CVV **na primeira cobrança** do cartão nelas. Depois, a própria conta guarda o cartão e as cobranças seguintes vão sem CVV. A SuyPay lembra disso por conta. - Passado o prazo, a SuyPay pula as contas que ainda precisariam do CVV e usa as outras. Se nenhuma servir, a cobrança falha com `account_not_enabled` e a mensagem explica. Por isso, cobre a primeira vez **logo depois** de salvar, enquanto o cliente está no checkout. ## Quais contas cobram cartão salvo | Conta | Cartão salvo | Primeira cobrança | Cobranças seguintes | Pede do cliente | |---|---|---|---|---| | Asaas | sim | com CVV | sem CVV (o Asaas guarda o cartão) | CPF/CNPJ, e-mail, celular, endereço | | Pagar.me | sim | com ou sem CVV | sem CVV | CPF/CNPJ, e-mail, endereço | | Mercado Pago | sim | com CVV | sem CVV, com "Pagamentos automáticos" liberado na conta | CPF/CNPJ, e-mail | | Appmax | sim | com CVV | sem CVV (token da Appmax) | CPF/CNPJ, e-mail, celular | | PagBank | sim | com CVV | sem CVV (o PagBank guarda o cartão) | CPF/CNPJ, e-mail, celular | | TriboPay | sim | com CVV | só enquanto houver CVV | CPF/CNPJ, e-mail, celular | | Conta de teste | sim | | | | | Stripe, Efí | não: use o token do formulário delas (`card.token`) | | | | | Wyvi Pay, Pagmaster | não: o cartão é pago na página delas | | | | ### Quando a conta esquece o cartão Depois da primeira cobrança, cada conta guarda a própria cópia do cartão (o `creditCardToken` do Asaas, o cartão do cliente no Mercado Pago e no PagBank). Se a conta não reconhecer mais essa cópia (foi apagada no painel dela, é de outro ambiente ou de outro cliente), a SuyPay apaga a cópia e cobra de novo com o cartão do cofre, na mesma hora. Quando a conta pede CVV para isso e ele já não existe, a cobrança volta com `invalid_card` e a mensagem para pedir o cartão de novo ao cliente. ## Apagar `DELETE /v1/cards/{id}` apaga o cartão também do cofre. Nenhuma conta consegue mais cobrar esse cartão pela SuyPay. Um cartão que paga uma assinatura ativa só pode ser apagado depois que a assinatura for cancelada. ## Link de pagamento No [link de pagamento](https://docs.suypay.com/payment-links.md), quando alguma conta aceita cartão salvo, o cliente digita o cartão nos campos da SuyPay, ali mesmo na página. O cartão fica salvo no cliente da cobrança, com `metadata.source = "payment_link"`. --- # Pix Automático Para mensalidades, planos e assinaturas. O cliente aprova **uma vez** no app do banco e, a cada ciclo, o valor sai sozinho da conta dele. Sem boleto, sem lembrete, sem cartão vencendo. ## Como funciona 1. Você cria o Pix Automático com o valor e a frequência. 2. A SuyPay devolve um **QR Code**. Mande para o cliente. 3. Ao escanear, o cliente paga o primeiro ciclo e autoriza os próximos no mesmo passo. 4. Nos próximos ciclos, o banco do cliente paga sozinho no vencimento. Cada ciclo vira uma cobrança normal em **Pagamentos**, com os mesmos avisos (`payment.succeeded`, `payment.failed`). ## Quais contas fazem | Conta | Pix Automático | Quem cria cada ciclo | |---|---|---| | Asaas | sim (peça a liberação ao Asaas) | a SuyPay, 3 dias antes do vencimento | | Woovi | sim | a própria Woovi, 4 dias antes do vencimento | | Conta de teste | sim | a SuyPay | | Mercado Pago, Efí, Stripe, Appmax | ainda não | | O provedor oferecer Pix Automático não garante que **a sua conta** esteja liberada. Em **Contas conectadas**, abra a conta e marque **Liberado**, **Não liberado** ou **Ainda não sei**. A SuyPay prefere contas confirmadas; se precisar, tenta as que ainda não foram confirmadas. Ela não usa as marcadas como não liberadas. Quando uma autorização funciona, marca a conta como liberada. Se o provedor recusar claramente o acesso ao recurso, marca como não liberada e tenta outra conta compatível. ## Criar Pelo painel, em **Pix Automático → Novo Pix Automático**. Ou pela API: ```bash curl https://api.suypay.com/v1/subscriptions \ -H "Authorization: Bearer suy_test_..." \ -H "Content-Type: application/json" \ -d '{ "frequency": "monthly", "amount": 4990, "description": "Plano mensal", "customer": { "name": "Ana Lima", "document": "52998224725" } }' ``` A resposta traz `status: "pending"` e, em `approval.qr_code`, o código que o cliente escaneia. O que você precisa saber: - **CPF ou CNPJ é obrigatório.** Na Woovi, o endereço completo do cliente também. - **Valor fixo ou variável.** Sem `amount`, o valor muda a cada ciclo (conta de consumo, por exemplo) e você informa o valor de cada um ao cobrar. Use `first_amount` para o primeiro. - **Nova tentativa.** Com `retry: true` (padrão), se faltar saldo o banco tenta de novo até 3 vezes em 7 dias. - **Frequências:** `weekly`, `monthly`, `quarterly`, `semiannually` e `annually`. ## Depois da aprovação Quando o cliente aprova, chega o aviso `subscription.activated`. Se ele não aprovar a tempo, ou o banco dele não confirmar, chega `subscription.refused`. Com valor fixo, a SuyPay cobra cada ciclo sozinho. Com valor variável, cobre quando souber o valor: ```bash curl https://api.suypay.com/v1/subscriptions/sub_.../charge \ -H "Authorization: Bearer suy_test_..." \ -H "Content-Type: application/json" \ -d '{ "amount": 7320, "due_date": "2026-11-10" }' ``` O vencimento precisa ficar entre **2 e 10 dias úteis** a partir de hoje. Essa é uma regra do Pix Automático, não da SuyPay. ## Cancelar Em **Cancelar** no painel ou `POST /v1/subscriptions/{id}/cancel`. Nenhum ciclo novo é cobrado e o cliente vê o cancelamento no app do banco. O cliente também pode cancelar pelo banco: nesse caso chega `subscription.canceled`. ## Testar No modo de teste, conecte a conta de teste, crie um Pix Automático e clique em **Simular aprovação**. O primeiro ciclo aparece pago na hora. --- # Assinatura por cartão Mensalidades no cartão de crédito. Quem cobra cada ciclo é a SuyPay, no [cartão salvo](https://docs.suypay.com/cards.md) do cliente, pela conta que as suas [regras](https://docs.suypay.com/rules.md) escolherem. Se uma conta falhar, outra assume. ## Criar Salve o cartão e crie a assinatura logo em seguida, com o cliente ainda no checkout: ```bash curl https://api.suypay.com/v1/subscriptions \ -H "Authorization: Bearer suy_test_..." \ -H "Content-Type: application/json" \ -d '{ "method": "card", "card_id": "card_4Fh...", "frequency": "monthly", "amount": 4990, "customer": { "name": "Ana Lima", "document": "52998224725", "email": "ana@exemplo.com" } }' ``` Começando hoje, a primeira cobrança acontece **na hora**, e a resposta traz o resultado em `latest_payment`: - **aprovada:** a assinatura fica `active` e chega `subscription.activated`; - **recusada:** a assinatura fica `refused` e chega `subscription.refused`. Com `start_date` no futuro, a assinatura já nasce `active` e a primeira cobrança sai nessa data. Nesse caso o CVV já terá sido apagado, então só servem contas que cobram sem CVV na primeira vez (Pagar.me, ou uma conta que já tenha cobrado esse cartão antes). ## Ciclos Todo dia a SuyPay cobra as assinaturas com vencimento no dia. Cada ciclo vira uma cobrança normal em **Pagamentos**, com `subscription_id` e `card`, e os avisos de sempre (`payment.succeeded`, `payment.failed`). As cobranças vão marcadas como recorrência para as bandeiras e saem sempre à vista (1x). Se um ciclo é recusado e `retry` está ligado (o padrão), a SuyPay tenta de novo **3 vezes, com 2 dias entre cada tentativa**. Se todas falharem, ou se `retry` estiver desligado, a assinatura fica `past_due` e chega `subscription.past_due`. Ela não é cobrada sozinha de novo até você agir: - `POST /v1/subscriptions/{id}/charge` cobra agora e, se aprovar, a assinatura volta a `active`; - ou peça outro cartão ao cliente, cancele a assinatura e crie outra com o cartão novo. Valor variável: crie sem `amount` e cobre cada ciclo com `POST /v1/subscriptions/{id}/charge` informando `amount`. ## Cancelar `POST /v1/subscriptions/{id}/cancel`. Nenhum ciclo novo é cobrado. O cartão continua salvo até você apagar. ## Pix Automático ou cartão? | | Pix Automático | Cartão | |---|---|---| | O cliente aprova | uma vez, no app do banco | digitando o cartão uma vez | | Quem cobra o ciclo | o banco do cliente | a SuyPay | | Troca de conta se uma falhar | não: a autorização é de uma conta | sim | | Cartão vencido ou sem limite | não se aplica | o ciclo falha e entra nas novas tentativas | --- # Devoluções Pelo painel, abra o pagamento e clique em **Devolver**. Você escolhe o valor, total ou parcial. Pelo código: ```bash curl -X POST https://api.suypay.com/v1/payments/pay_.../refund \ -H "Authorization: Bearer suy_live_..." \ -H "Content-Type: application/json" \ -d '{ "amount": 500 }' ``` Sem `amount`, devolve tudo o que ainda não foi devolvido. Você pode fazer várias devoluções parciais. Mande o cabeçalho `Idempotency-Key` para poder repetir o pedido sem medo: se a primeira tentativa já tinha passado, a resposta traz a mesma devolução, e o dinheiro não sai duas vezes. ```json { "refund": { "id": "re_9Lm...", "object": "refund", "payment_id": "pay_3kXy...", "amount": 500, "status": "pending", "source": "suypay" }, "payment": { "id": "pay_3kXy...", "status": "partially_refunded", "amount_refunded": 500 } } ``` ## Situação da devolução | `status` | O que quer dizer | |---|---| | `pending` | a conta recebeu o pedido e ainda está devolvendo | | `succeeded` | o dinheiro voltou para o cliente | | `failed` | a conta não conseguiu devolver. O valor volta a contar como recebido | Muitas contas devolvem na hora. Algumas, como a Appmax e o Pix de várias contas, levam um tempo. Quando a situação muda, chega o aviso `refund.updated`. A SuyPay também confere de novo, todo dia, as devoluções que ainda estão em andamento. ## Devoluções feitas no painel da conta Se você devolver direto no painel do Mercado Pago, do Asaas ou de outra conta, a SuyPay fica sabendo pelo aviso da conta (ou na [conferência](https://docs.suypay.com/reconciliation.md)) e registra a devolução com `source: "provider"`. O pagamento, o valor devolvido e os relatórios ficam certos sem você fazer nada, e chega o aviso `refund.created`. | Conta | O que a SuyPay vê | |---|---| | Mercado Pago, Stripe, Efí Bank (Pix) | cada devolução, com a situação dela | | Asaas, Appmax, Efí Bank (cartão) | o total devolvido | | Woovi | só as devoluções pedidas pela SuyPay | Chargeback e MED perdidos não aparecem como devolução: eles ficam em [Contestações](https://docs.suypay.com/disputes.md). ## O que cada conta permite | Conta | Pix | Cartão | Boleto | |---|---|---|---| | Mercado Pago | sim | sim | sim | | Asaas | sim | sim | não | | Efí Bank | sim | sim | não | | Stripe | sim | sim | não | | Appmax | sim | sim | não | | Woovi | sim | — | — | Quando a conta não deixa devolver por aqui, a resposta vem com `code: "not_refundable"`. Devolva pelo painel dela: a SuyPay registra do mesmo jeito. > **Atenção:** no modo Real, o dinheiro volta para o cliente de verdade. --- # Contestações (MED e chargeback) Às vezes o cliente pede o dinheiro de volta pelo banco, sem falar com você: - **MED** (Mecanismo Especial de Devolução): no Pix, quando o cliente diz que caiu num golpe ou não recebeu o que comprou. - **Chargeback**: no cartão, quando o cliente não reconhece a compra. Nos dois casos existe um **prazo** para você mostrar que a venda é legítima. Se ninguém responde, o dinheiro volta para o cliente. ## Onde aparece Em **Contestações** no painel, com as abertas no topo e ordenadas pelo prazo. A página inicial também avisa quando tem alguma esperando resposta, e o pagamento ganha um aviso com o botão **Responder**. Pela API, `GET /v1/disputes?status=open`. E pelos avisos `dispute.created`, `dispute.updated` e `dispute.closed`. ## Como cada conta trata Nem toda conta avisa contestações pela API. Algumas cuidam de tudo no próprio painel; nesses casos a SuyPay mostra, em **Contestações**, onde responder, e marca o pagamento como devolvido se o dinheiro voltar ao cliente. | Conta | Aviso na SuyPay | Responder pela SuyPay | O que a defesa aceita | |---|---|---|---| | Stripe | chargeback | sim | texto e links, e cada prova no campo próprio (cliente, IP, rastreio, acessos) | | Woovi | MED | sim | texto (até 500) e pelo menos um link | | ClownPay | MED | sim | texto (10 a 3.000) e de 1 a 10 links | | Wyvi Pay | MED | sim | só texto, de 20 a 1.000 caracteres, **sem links** | | Efí | MED (a SuyPay consulta todo dia e ao abrir Contestações) | sim | texto de 20 a 1.000 caracteres | | Mercado Pago | chargeback | não, responda no painel do Mercado Pago | | | Asaas | chargeback | não, responda no painel do Asaas | | | Appmax | chargeback | não, responda no painel da Appmax | | | InvictusPay | MED e chargeback | não, responda no painel da InvictusPay | | | Pagar.me | chargeback perdido | não, a defesa é no painel do Pagar.me | | | Inter, EvoPay, TriboPay, RivooPay, Pagmaster, PagBank | não avisam pela API | responda no painel da conta | | Para os avisos chegarem, o endereço de avisos da conta precisa estar cadastrado nela com os eventos de contestação. Veja [Conectar contas](https://docs.suypay.com/connections.md). Na Efí, a aplicação precisa dos escopos `gn.infractions.read` e `gn.infractions.write`; na Wyvi Pay, a chave precisa de `disputa:responder`. > A defesa é uma só por contestação na maioria das contas: depois de enviada, não dá para corrigir. A SuyPay confere o tamanho do texto e os links de acordo com a conta antes de mandar. ## Defesa automática Toda contestação ganha uma defesa assim que chega, MED ou chargeback, sem você fazer nada. A SuyPay junta as provas da venda, escreve o texto (com IA; se a IA estiver fora do ar, por um modelo com os mesmos fatos) e: - Nas contas que recebem a defesa pela API (Woovi, ClownPay, Wyvi Pay, Efí, Stripe), **envia na hora**, no tamanho e com os links que cada conta aceita. Na lista aparece **Defesa enviada**. - Nas outras, a defesa fica pronta em **Contestações**: abra, copie e cole no painel da conta. - Se o envio falhar, o texto vem preenchido em **Responder** para você conferir e mandar. A SuyPay também tenta de novo todo dia. A defesa usa só fatos registrados e nunca inventa pedido, nota ou rastreio. ### O que decide um MED O MED não é um chargeback. Pelo [Guia do MED do Banco Central](https://www.bcb.gov.br/estabilidadefinanceira/pix), ele só cabe com **fundada suspeita de fraude cometida pelo recebedor** ou com falha operacional de um banco. Não basta o pagador dizer que não reconhece a compra: o banco dele precisa indicar que o vendedor foi quem aplicou o golpe. A defesa responde ao motivo com a regra certa: | Motivo informado | O que a defesa mostra | |---|---| | Golpe, fraude, não reconhece | não houve fraude do vendedor; quem pagou foi identificado e pagou na sua página; dinheiro usado para comprar de um terceiro de boa-fé não volta | | Não recebeu | a entrega (rastreio, data, acessos, nota). Sem a entrega, este é o caso mais difícil | | Atraso, não gostou, diferente do esperado | desacordo comercial não é hipótese de MED; se resolve na Justiça | | Pix errado, repetido, arrependimento | erro do pagador não é hipótese de MED | | Falha operacional | o Pix foi iniciado pelo pagador e caiu no valor certo | ### Provas que a SuyPay junta | Prova | De onde vem | |---|---| | Pagamento confirmado | valor, data e hora, identificador do Pix (E2E) | | Comprador identificado | nome, CPF/CNPJ, e-mail e celular da cobrança | | Pagou na sua página | aparelho, navegador e IP de quem gerou o Pix ou digitou o cartão na página de pagamento, com a hora | | Comprovante aberto | quando o comprador abriu o comprovante depois de pagar | | **Entrega comprovada** | o que você registrar: rastreio, entrega, acessos, nota fiscal. **A prova que mais pesa** | | Cliente recorrente | compras anteriores pagas e nenhuma outra contestação | Em **Contestações**, cada uma mostra essa lista, com o que já está provado e o que falta. Pela API: `GET /v1/disputes/:id/proofs`. ### Registre a entrega Assim que enviar o produto ou liberar o acesso, registre. Se o cliente contestar depois, a prova já está lá. No painel, abra o pagamento e use **Comprovar entrega**. Pela API: ```bash curl https://api.suypay.com/v1/payments/pay_.../fulfillment \ -H "Authorization: Bearer suy_test_..." \ -H "Content-Type: application/json" \ -d '{ "type": "digital", "access_granted_at": "2026-10-21T14:30:00-03:00", "access_log": [{ "at": "2026-10-21T15:02:00-03:00", "what": "Assistiu à aula 1", "ip": "189.40.12.34" }], "invoice_number": "1042" }' ``` `type` é `physical` (produto enviado: `carrier`, `tracking_code`, `tracking_url`, `delivered_at`, `delivered_to`), `digital` (acesso ou arquivo: `access_granted_at`, `access_log`) ou `service`. Também valem `invoice_number`, `invoice_url`, `customer_contact` e até 10 `urls`. Cada envio troca os campos mandados e mantém os outros; `access_log` vai somando (até 30). Se houver uma contestação aberta sem defesa enviada, ela é escrita de novo com a prova nova. Pelo MCP, a ferramenta é `record_fulfillment`. ### Dossiê da venda O primeiro link de prova de toda defesa é o **dossiê**: uma página com tudo o que a SuyPay sabe da venda, a regra do Banco Central e a lista de provas, com CPF e IP mascarados. Quem analisa no banco lê os fatos, não só o seu texto. O endereço não dá para adivinhar e está em `GET /v1/disputes/:id/proofs` (`dossier_url`). ### Perdeu? Ainda dá para contestar Desde 01/09/2026 (Instrução Normativa BCB 766/2026), quem recebeu de forma legítima e teve o dinheiro devolvido por um MED pode contestar a devolução em **até 80 dias**. Quando um MED é perdido, a SuyPay já escreve essa contestação: abra o MED em **Contestações**, copie e envie ao atendimento da conta antes do prazo que aparece ali. O objeto `dispute` traz tudo em `auto_defense`: `text`, `urls`, `sent`, `error`, `ground` (o motivo entendido), `by` (`ai` ou `template`) e, num MED perdido, `contest` (`text`, `urls`, `until`). ## Responder Conte o que foi vendido, quando foi entregue e para quem, com número do pedido, nota ou rastreio. Nas contas que aceitam links, junte links públicos das provas: nota fiscal, comprovante de entrega, conversa. Na Wyvi Pay, descreva as provas só no texto: ela recusa qualquer link. ```bash curl https://api.suypay.com/v1/disputes/dp_.../evidence \ -H "Authorization: Bearer suy_test_..." \ -H "Content-Type: application/json" \ -d '{ "text": "Plano anual comprado em 12/10. O cliente acessou 8 vezes e recebeu a nota fiscal por e-mail.", "urls": ["https://sualoja.com/nf/1042.pdf"] }' ``` ## Situações | `status` | Quer dizer | |---|---| | `open` | esperando a sua resposta | | `under_review` | resposta enviada, o banco está analisando | | `won` | você ganhou, o dinheiro fica com você | | `lost` | o dinheiro voltou para o cliente. O pagamento passa para `refunded` | | `canceled` | o cliente desistiu da contestação | ## Testar No modo de teste, abra um pagamento já pago da conta de teste e clique em **Simular contestação**. --- # Saques e transferências Em **Saques**, o painel mostra o saldo de cada conta conectada e tira dinheiro dela: para a sua conta bancária ou para uma chave Pix que você salvou. Tudo que sai fica registrado, com a situação de cada envio e um aviso no seu [webhook](https://docs.suypay.com/webhooks.md). ## Quais contas sacam pela API | Conta | Para onde | Taxa | |---|---|---| | Asaas | chave Pix salva | somada ao valor | | Stripe | conta bancária cadastrada na Stripe | da Stripe | | Pagar.me | conta bancária do recebedor principal | sai de dentro do valor | | Wyvi Pay | chave Pix salva (mínimo R$ 0,30) | somada ao valor | | Pagmaster | chave Pix salva (R$ 10 a R$ 10.000) | sai de dentro do valor | | ClownPay | conta cadastrada na ClownPay ou chave Pix salva | somada ao valor | | InvictusPay | chave Pix salva | somada ao valor | | TriboPay | conta cadastrada na TriboPay (mínimo R$ 10) | sai de dentro do valor | | Conta de teste | as duas, com saldo fictício | nenhuma | Mercado Pago, Efí, Appmax, Woovi, EvoPay, Inter e RivooPay não oferecem saque pela API (ou pedem liberação especial). Saques de [subcontas](https://docs.suypay.com/subaccounts.md) aparecem aqui também. Nelas, o saldo aparece quando a conta informa e o saque é feito no painel delas. > **Dica:** "conta cadastrada" é a conta bancária ou chave que você validou **dentro** do provedor. É o destino mais seguro: ninguém consegue mudá-lo pela SuyPay. ## O que protege o seu dinheiro - **Chaves salvas.** Saques para terceiros só vão para chaves Pix salvas em **Saques → Chaves Pix salvas**. Só o dono da empresa salva ou remove chaves, e só pelo painel: uma chave de API não cria destinos. - **Espera de 1 hora.** Uma chave nova só recebe saques reais 1 hora depois de salva, e todos os seus webhooks recebem `payout_destination.created`. Se alguém entrar na sua conta e salvar uma chave, dá tempo de ver e remover. - **Limite de 24 horas.** A soma dos saques da empresa em 24 horas tem um teto (R$ 5.000,00 até você mudar). Ele é conferido com uma trava: dois pedidos ao mesmo tempo não passam juntos por baixo do limite. - **API desligada por padrão.** Saques pela API só funcionam depois que o dono liga em **Saques → Segurança**. Chaves **só cobranças** nunca sacam. - **Sem saque em dobro.** Cada saque tem uma `Idempotency-Key`. Repetir o pedido devolve o mesmo saque. Se a conta não responder (queda, demora), o saque fica **Confirmando** (`uncertain: true`) e a SuyPay consulta de novo; ele nunca é reenviado às cegas nem trocado de conta. ## Situações | Situação | Quer dizer | |---|---| | `pending` | registrado, ainda não saiu | | `processing` | a conta aceitou e o dinheiro está a caminho | | `paid` | chegou | | `failed` | a conta recusou ou o banco devolveu; o motivo vem em `failure_reason` | | `canceled` | cancelado antes de sair | ## Pela API Veja [Saques na referência da API](https://docs.suypay.com/api-payouts.md). --- # Subcontas e split Uma **subconta** é um vendedor, parceiro ou filial que recebe parte das suas vendas. Ela fica dentro de uma conta conectada, e cada cobrança feita por essa conta pode dizer quanto vai para cada subconta. É o **split**: a conta divide o dinheiro sozinha quando o cliente paga, sem você transferir nada depois. Serve para marketplace (cada loja recebe a sua parte), comissão de afiliado ou vendedor, sócio que recebe uma porcentagem e franquia que repassa para a matriz. ## Quais contas fazem | Conta | Como a subconta recebe | Cadastro do titular | Split em | |---|---|---|---| | Pagar.me | na conta bancária do titular, por repasse automático ou saque pela SuyPay | link de prova de vida (KYC) | Pix, boleto e cartão | | Asaas | numa conta Asaas própria, com login e app | link de envio de documentos | Pix, boleto e cartão | | Woovi | num saldo que sai de uma vez para a chave Pix do titular | não precisa | Pix | | Wyvi Pay | numa conta Wyvi do titular, sacada para a chave Pix salva na criação. Só pessoa física pela API | não precisa (CPF, e-mail, nascimento e CEP) | Pix, sobre o valor líquido | | Pagmaster | num saldo separado dentro da sua conta, sacado para a chave Pix salva na criação | não precisa | não divide: a cobrança inteira entra na subconta (Pix e cartão) | | Conta de teste | saldo fictício | link de teste que aprova na hora | Pix, boleto e cartão | A Pagar.me só faz split em contas com a adquirência Pagar.me (PSP). O Asaas só cria subcontas para contas com CNPJ. Na Woovi, o recurso de subconta precisa estar liberado na conta. ## Criar uma subconta Em **Subcontas → Nova subconta**, escolha a conta e preencha o titular. O formulário pede só o que aquela conta exige: - **Pagar.me:** e-mail, celular, data de nascimento, nome da mãe, profissão, renda mensal, endereço e a conta bancária (no mesmo CPF/CNPJ). Para empresa, também razão social, tipo, data de abertura, faturamento anual e o sócio administrador. - **Asaas:** e-mail, celular, renda ou faturamento mensal e endereço; data de nascimento para pessoa física e tipo de empresa para CNPJ. - **Woovi:** só o nome e a chave Pix do titular. A Woovi confere se a chave existe. Toda subconta nova avisa seus [webhooks](https://docs.suypay.com/webhooks.md) com `subaccount.created`. ## Situações | Situação | Quer dizer | |---|---| | Em cadastro (`pending`) | criada, mas o titular ainda precisa concluir o cadastro ou a conta está analisando. Já recebe split; ainda não saca | | Ativa (`active`) | aprovada: recebe e saca | | Recusada (`refused`) | a conta não aprovou o cadastro. Não recebe split | | Bloqueada (`blocked`) | suspensa ou bloqueada pela conta. Não recebe split | | Inativa (`inactive`) | encerrada pela conta | Na Pagar.me e no Asaas, abra a subconta e toque em **Link de cadastro**: mande o link ao titular para ele provar a identidade e enviar documentos. A situação muda sozinha quando a conta avisa (`subaccount.updated`); a SuyPay também confere uma vez por dia, e o botão **Atualizar situação** consulta na hora. ## Pagmaster: a venda inteira na subconta A Pagmaster não divide uma venda. Em vez disso, a cobrança é criada **dentro** da subconta e o valor todo entra no saldo dela, que paga a taxa. Na cobrança, escolha **Receber numa subconta**; pela API, mande uma parte só, sem `amount`: ```json { "splits": [{ "subaccount_id": "sub_..." }] } ``` ## Dividir uma venda Na **Nova cobrança**, toque em **Dividir o valor com subcontas**, escolha cada subconta e quanto ela recebe, em reais ou em porcentagem do valor da venda. Pela API, mande `splits`: ```json { "method": "pix", "amount": 10000, "customer": { "name": "Maria Silva", "document": "12345678909", "email": "maria@email.com", "phone": "11912345678" }, "splits": [ { "subaccount_id": "sub_loja1", "amount": 7000 }, { "subaccount_id": "sub_afiliado", "percentage": 5 } ] } ``` Regras: - **A conta principal fica com o resto e paga as taxas.** As partes somam menos que o valor, e sobra o bastante para a taxa estimada. No exemplo, a conta principal fica com R$ 25,00 e paga a taxa com eles. - **Porcentagem é do valor da venda**, antes das taxas, e a SuyPay guarda a parte já em centavos. - **As subcontas de uma venda são da mesma conta conectada.** A cobrança vai por essa conta, sem passar pelas [regras](https://docs.suypay.com/rules.md) e sem troca automática de conta. - **A conta principal responde por devoluções e chargebacks.** Uma devolução feita depois sai na proporção que a conta decidir. - Chaves **só cobranças** não mandam `splits`: split é dinheiro saindo para outra pessoa. No link de pagamento sem forma definida, o cliente só vê as formas em que a conta faz split. ## Saldo e saques da subconta Abra a subconta para ver o saldo (Pagar.me, Asaas, Woovi) e as vendas que mandaram dinheiro para ela. - **Pagar.me:** **Sacar** manda o valor para a conta bancária do titular. Ou ligue o **repasse automático** (todo dia, semana ou mês) ao criar a subconta. - **Woovi:** **Sacar** manda o saldo inteiro para a chave Pix do titular. - **Asaas:** o titular saca pelo app ou site do Asaas, com o login da subconta. O saque da subconta só vai para o destino dela, cadastrado na conta ao criar. Ninguém escolhe outro destino pela SuyPay, por isso ele não conta no limite de 24 horas dos [saques](https://docs.suypay.com/payouts.md). Pela API, ele precisa de **Saques pela API** ligado, como qualquer saque, e de uma `Idempotency-Key`. ## Pela API Veja [Subcontas e split](https://docs.suypay.com/api-subaccounts.md) na referência. --- # Conectar contas Em **Contas conectadas → Conectar conta**, escolha onde você recebe, dê um nome à conta e cole as chaves de acesso. A SuyPay testa a conexão na hora e guarda as chaves com criptografia. Elas nunca voltam para a tela. Se as mesmas chaves já estiverem conectadas a outra conta do mesmo provedor e ambiente na sua organização, a SuyPay impede o cadastro. A comparação usa uma assinatura criptográfica das chaves de autenticação; chaves diferentes da mesma conta no provedor ainda podem passar. Cada conta conectada tem um **endereço de avisos**. É por ele que a conta conta à SuyPay quando o cliente paga. Em contas cujo provedor oferece Pix Automático, informe se **a sua conta** tem o recurso liberado. Se não souber, deixe **Ainda não sei**: a SuyPay tenta usar a conta depois das confirmadas e atualiza a situação quando receber uma resposta clara. Contas marcadas como **Não liberado** não recebem novos Pix Automáticos. A situação não afeta Pix comum, boleto ou cartão. ## Mercado Pago 1. No Mercado Pago, vá em **Suas integrações → Credenciais**. 2. Copie o **Access Token**. Para o modo de teste, use o que começa com `TEST-`. 3. Cole na SuyPay. Os avisos são configurados sozinhos, então não precisa fazer mais nada. ## Asaas 1. No Asaas, vá em **Integrações → Chave de API** e gere uma chave. 2. Cole na SuyPay. 3. Em **Integrações → Webhooks**, crie um webhook com o **endereço de avisos** da conta (fica no menu ⋯ dela) e marque os eventos de cobrança e de Pix Automático. Configure um token no webhook e informe o mesmo token na conexão SuyPay para que mudanças de elegibilidade do Pix Automático sejam aceitas. > **Dica:** o Asaas sempre pede o CPF ou CNPJ do cliente. ## Efí Bank 1. Na Efí, vá em **API → Aplicações** e copie o **Client ID** e o **Client Secret**. 2. Para receber Pix, adicione também a sua **chave Pix** e o **certificado** (.p12, em API → Meus certificados). Boleto e cartão avisam a SuyPay sozinhos. Para o Pix, cadastre o endereço de avisos no webhook da sua chave Pix, no painel da Efí. ## Stripe 1. No Stripe, vá em **Desenvolvedores → Chaves de API** e copie a **chave secreta**. 2. Em **Desenvolvedores → Webhooks**, adicione o endereço de avisos com os eventos `payment_intent.*`, `checkout.session.completed`, `checkout.session.expired`, `checkout.session.async_payment_succeeded`, `checkout.session.async_payment_failed`, `charge.refunded` e `charge.dispute.*`. Pix e boleto pelo Stripe exigem uma conta Stripe no Brasil. ## Pagar.me 1. Na Pagar.me, vá em **Desenvolvimento → Chaves** e copie a **chave secreta**. Para o modo de teste, use a que começa com `sk_test_`. 2. Para ver o saldo, sacar, criar [subcontas](https://docs.suypay.com/subaccounts.md) e dividir pagamentos, copie também o **ID do recebedor principal** (em **Configurações → Recebedores**, começa com `re_`, `rp_` ou `pp_`). 3. Em **Configurações → Webhooks**, crie um webhook com o **endereço de avisos** da conta e marque `charge.paid`, `charge.pending`, `charge.payment_failed`, `charge.refunded`, `charge.partial_canceled`, `order.canceled` e `recipient.updated`. A Pagar.me pede CPF ou CNPJ e e-mail do cliente; Pix também pede celular, e boleto, endereço. No cartão, use o [cartão salvo](https://docs.suypay.com/cards.md) ou o token do formulário de cartão da Pagar.me no seu site (`token_…`, gerado com a chave pública). Split e recebedores só funcionam em contas com a adquirência Pagar.me (PSP). ## Appmax 1. Na Appmax, vá no menu **API → Credenciais → Gerar credenciais**, escolha a loja e copie o **Client ID** e o **Client Secret**. O secret aparece uma vez só. 2. Cole na SuyPay. 3. Na aba **Webhooks** da mesma tela, escolha a loja, cole o endereço de avisos e marque os eventos de **Pedidos** e **Pagamentos**. > **Dica:** a Appmax sempre pede e-mail e celular do cliente, e CPF ou CNPJ para boleto e cartão. Se faltar algum, a SuyPay pula a Appmax e usa a próxima conta. ## Woovi 1. Na Woovi, vá em **API/Plugins → Nova API** e copie o **AppID**. Para o modo de teste, crie a chave em `app.woovi-sandbox.com`. 2. Cole na SuyPay. 3. Em **API/Plugins → Novo webhook**, cadastre o endereço de avisos para os eventos de cobrança, de Pix Automático e de disputa. A Woovi recebe só Pix, mas faz [Pix Automático](https://docs.suypay.com/pix-automatico.md) e avisa os [MED](https://docs.suypay.com/disputes.md). ## EvoPay 1. Na EvoPay, abra **Configurações → Token** e copie o token API da conta. 2. Conecte a conta em **produção** e confira as taxas do seu contrato. A API publicada pela EvoPay não oferece ambiente de testes. A EvoPay recebe o endereço de avisos em cada cobrança Pix e tenta entregar cada aviso uma vez só. A SuyPay consulta a API da EvoPay antes de aceitar um aviso e confere as cobranças em aberto na conciliação, então um aviso perdido não deixa a venda para trás. A API não faz estorno nem Pix Automático: devolva pelo painel da EvoPay e a SuyPay registra a devolução. ## Inter 1. No Inter Empresas, crie uma integração com permissões de cobrança Pix e baixe o certificado e a chave privada PEM. Use as credenciais e o certificado do mesmo ambiente que selecionar na SuyPay. 2. Copie o **Client ID**, o **Client Secret** e a chave Pix recebedora. Cole tudo na SuyPay, mantendo as linhas completas dos arquivos PEM. Se a integração estiver ligada a mais de uma conta corrente, informe também o número da conta. 3. Configure no Inter o webhook Pix dessa chave com o **endereço de avisos** da conta conectada. O Inter usa OAuth e certificado mTLS. A SuyPay guarda as credenciais criptografadas, reutiliza o token até perto de expirar e confere os avisos na API antes de atualizar pagamentos. No modo de teste, o botão **Simular pagamento** paga a cobrança pelo sandbox do Inter. O Inter publica Pix Automático, mas a integração SuyPay desta conta ainda não expõe a jornada de recorrência; mantenha assinaturas em uma conta que já suporte o fluxo completo. ## Wyvi Pay 1. No painel da Wyvi Pay, abra **Chaves de API** e crie uma chave. Use `wy_test_…` no modo de teste e `wy_live_…` no modo real (o endereço da API é o mesmo; a chave decide o ambiente). Para fazer [saques](https://docs.suypay.com/payouts.md), marque o escopo `transferencia:criar`; para [subcontas](https://docs.suypay.com/subaccounts.md), `subconta:criar` e `subconta:ler`; para responder [MED](https://docs.suypay.com/disputes.md), `disputa:responder`. 2. Cole na SuyPay. 3. Em **Webhooks**, crie um destino com o **endereço de avisos** e os eventos `cobranca.*`, `reembolso.*` e `transferencia.*`. Copie o segredo `whsec_…` (ele aparece uma vez só) e cole em **Editar → Chaves**. A Wyvi Pay recebe Pix e cartão. O cartão abre a página segura da Wyvi Pay, não existe no modo de teste e não é devolvido pela API. Pix pode ser devolvido no todo ou em parte. Para receber avisos de MED e de subcontas, assine também os eventos `med.*` e `subconta.*` no webhook da Wyvi Pay. ## Pagmaster 1. Na Pagmaster, abra **Integrações → Keys** e crie uma chave `mk_live_…` com as permissões `read` e `charges` (e `transfers`, para [saques](https://docs.suypay.com/payouts.md); `subaccounts`, para [subcontas](https://docs.suypay.com/subaccounts.md)). 2. Cole na SuyPay. Se quiser receber por uma subconta, informe o UUID dela. 3. Em **Integrações → Webhooks**, cadastre o endereço de avisos e cole o segredo `whsec_…` na SuyPay. A Pagmaster recebe Pix de R$ 2 a R$ 2.000 e cartão de R$ 5 a R$ 2.000 numa página segura. Não publica ambiente de testes nem devolução pela API, e trata MED no painel dela. ## ClownPay 1. Na ClownPay, com o KYC aprovado, abra **Integrações → Credenciais** e copie a credencial `cp_live_…`. 2. Cole na SuyPay. 3. Em **Integrações → Webhooks**, crie o webhook com o endereço de avisos, marque os eventos de pagamento, saque e MED e cole o segredo mostrado na SuyPay. A ClownPay pede **nome, CPF/CNPJ, celular e e-mail** em toda cobrança. As chaves `cp_test_` só consultam dados, então a conta funciona no modo real. MED aparece em [Contestações](https://docs.suypay.com/disputes.md) e pode ser respondido pela SuyPay. ## InvictusPay 1. Na InvictusPay, abra **Configurações → Credenciais de API** e gere uma chave (ela aparece uma vez só). 2. Cole na SuyPay. A SuyPay manda o endereço de avisos em cada cobrança. Para acompanhar [saques](https://docs.suypay.com/payouts.md), cadastre o mesmo endereço em **Webhooks** com o evento de saque. A InvictusPay recebe Pix e boleto pela SuyPay e pede nome, e-mail, CPF/CNPJ e celular. O cartão dela ainda não tem a API publicada; quando tiver, entra pelo [cartão salvo](https://docs.suypay.com/cards.md). ## TriboPay 1. Na TriboPay, abra **Configurações → API** e copie o token. 2. A TriboPay só vende por uma **oferta**: crie um produto e uma oferta no painel e copie os hashes dos dois. O valor de cada cobrança vem da SuyPay, não do preço cadastrado. 3. Cole o token e os dois hashes na SuyPay. A TriboPay recebe o endereço de avisos em cada cobrança. Recebe Pix e boleto (boleto pede endereço) e saca para a conta bancária cadastrada no painel dela. ## PagBank 1. No PagBank, abra **Minha conta → Integrações → Gerar token** e copie o token. Para o modo de teste, crie uma conta em `portaldev.pagbank.com.br` e gere o token do sandbox. 2. Cole na SuyPay, no modo certo. O PagBank recebe o endereço de avisos em cada pedido, então não há nada para cadastrar no painel dele. Cada aviso é conferido lendo o pedido de volta na API. Recebe Pix, boleto (pede endereço) e o [cartão salvo](https://docs.suypay.com/cards.md): a primeira cobrança vai com o CVV e o PagBank guarda o cartão para as próximas, inclusive em [assinaturas](https://docs.suypay.com/card-subscriptions.md). MED e chargeback são tratados no painel do PagBank. ## RivooPay 1. Copie a chave de API no painel da RivooPay. 2. Cole na SuyPay. A mesma chave serve aos dois modos: no modo de teste a SuyPay cria as cobranças como teste (`devMode`) e o botão **Simular pagamento** confirma pela API da RivooPay. 3. Em **Webhooks**, cadastre o endereço de avisos com os eventos de cobrança. A RivooPay recebe Pix a partir de R$ 5 e pede CPF/CNPJ, e-mail e celular. ## AbacatePay 1. Na AbacatePay, crie uma chave em **Integrações › Chaves de API** com as permissões `TRANSPARENT:CREATE` e `TRANSPARENT:READ`. A chave do modo dev vai no ambiente de teste; a de produção, no real. 2. Cole na SuyPay, no modo certo. 3. Em **Webhooks**, crie um webhook versão 2 com o endereço de avisos e os eventos `transparent.completed`, `transparent.refunded`, `transparent.disputed` e `transparent.lost`. Escolha um secret e cole também na SuyPay (**Editar › Chaves**). A AbacatePay recebe Pix a partir de R$ 1. No teste, o botão **Simular pagamento** confirma pela API dela. A devolução é sempre do valor inteiro. ## O que cada conta faz | Conta | Pix | Boleto | Cartão | Cartão salvo | Pix Automático | Contestações | Parcelas | Saques pela API | Subcontas e split | |---|---|---|---|---|---|---|---|---|---| | Mercado Pago | sim | sim | sim | sim | | aviso | até 12x | | | | Asaas | sim | sim | sim | sim | sim | aviso | até 21x | chave Pix | sim | | Efí | sim | sim | sim | | | MED: aviso (consulta diária) e resposta | até 12x | | | | Stripe | sim | sim | sim | | | aviso e resposta | até 12x | conta bancária cadastrada | | | Pagar.me | sim | sim | sim | sim | | chargeback perdido | até 12x | conta bancária cadastrada | sim | | Appmax | sim | sim | sim | sim | | aviso | até 12x | | | | Woovi | sim | | | | sim | aviso e resposta | | | sim (Pix) | | EvoPay | sim | | | | | no painel da EvoPay | | | | | Inter | sim | | | | | no app do Inter | | | | | Wyvi Pay | sim | | página segura | | | MED: aviso e resposta (só texto) | | chave Pix | sim (Pix, pessoa física) | | Pagmaster | sim | | página segura | | | no painel da Pagmaster | | chave Pix | subcontas (venda inteira) | | ClownPay | sim | | | | | aviso e resposta | | conta cadastrada e chave Pix | | | InvictusPay | sim | sim | | | | aviso | | chave Pix | | | PagBank | sim | sim | cartão salvo | sim | | no painel do PagBank | até 12x | | | | TriboPay | sim | sim | cartão salvo | sim (1ª cobrança) | | no painel da TriboPay | | conta cadastrada | | | RivooPay | sim | | | | | no painel da RivooPay | | | | | AbacatePay | sim | | | | | no painel da AbacatePay | | | | [Cartão salvo](https://docs.suypay.com/cards.md): o cliente digita o cartão uma vez nos campos da SuyPay e qualquer conta marcada aqui cobra, inclusive em [assinaturas](https://docs.suypay.com/card-subscriptions.md). ## Contas que pedem mais dados Algumas contas não aceitam a venda sem certos dados do cliente. A SuyPay sabe disso: se faltar um dado que uma conta exige, ela é **pulada** (aparece como "Pulada" no histórico da cobrança) e a venda vai pela próxima. | Conta | Pede sempre | |---|---| | Mercado Pago | e-mail; boleto também pede CPF/CNPJ e endereço | | Asaas | CPF ou CNPJ | | Efí | CPF ou CNPJ em boleto e cartão; no cartão, e-mail e celular | | Stripe | no boleto, CPF/CNPJ, e-mail e endereço | | Pagar.me | CPF ou CNPJ e e-mail; Pix também pede celular, e boleto, endereço | | Appmax | e-mail e celular; CPF ou CNPJ em boleto e cartão | | Wyvi Pay | CPF ou CNPJ no cartão | | ClownPay, InvictusPay, RivooPay | CPF ou CNPJ, e-mail e celular | | PagBank | CPF ou CNPJ e e-mail; cartão também pede celular, e boleto, endereço | | TriboPay | CPF ou CNPJ, e-mail e celular; boleto também pede endereço | ## Taxas Ao conectar, confira as taxas que você paga em cada conta. A SuyPay usa esses valores para escolher a mais barata, e a [conferência](https://docs.suypay.com/reconciliation.md) diária ajusta tudo com o valor real cobrado. O formulário mostra primeiro as chaves de acesso e a opção de buscar taxas. Abra **Ver ou preencher taxas manualmente** quando precisar editar os valores. Para cada forma de pagamento, informe o percentual e o valor fixo. Se o contrato cobrar pelo menos um valor ou limitar a taxa a um teto, marque **Usar taxa mínima** e/ou **Usar taxa máxima** e informe os valores. Desmarque para remover um limite. Eles são opcionais e valem para qualquer conta conectada. A SuyPay estima a taxa como percentual mais valor fixo, respeitando os limites que você informou. No cartão, a taxa principal vale para **1x**. Abra **Taxas por parcela** para adicionar uma taxa própria para cada quantidade aceita pela conta. Parcelas sem taxa própria usam a taxa de 1x; o mínimo e o máximo do cartão continuam valendo. A SuyPay usa a quantidade de parcelas da cobrança tanto para estimar a taxa quanto para escolher a conta. A lista vai só até o limite que cada provedor declara; contas sem cartão não mostram essa opção. No Asaas, depois de informar a chave de API, toque em **Buscar taxas da conta**. O botão indica **Configure primeiro** enquanto faltarem chaves. A SuyPay usa a [consulta autenticada do Asaas](https://docs.asaas.com/reference/recuperar-taxas-da-conta) para preencher Pix, boleto, cartão à vista e as faixas de parcelamento que a API devolver. Confira antes de conectar ou salvar: franquias mensais gratuitas de Pix não entram na estimativa, e parcelas sem faixa devolvida pela API continuam usando a taxa de 1x. Se a API devolver um desconto com prazo, a tela avisa para buscar as taxas novamente depois do vencimento. O botão também aparece nos outros provedores, mas indica quando a consulta da **taxa contratual da loja** não está disponível; nesses casos, preencha as taxas conforme seu contrato. As rotas de [parcelas da Appmax](https://docs.appmax.com.br/guides/calculo-parcelas) e da [Efí](https://dev.efipay.com.br/docs/api-cobrancas/cartao/) calculam valores e juros do parcelamento, que podem ser cobrados do cliente; esses valores não devem ser confundidos com a taxa cobrada da loja. Uma transação isolada também não representa necessariamente as taxas da conta. Em **Contas conectadas**, passe o mouse sobre a conta ou toque e segure para revelar a alça dentro da borda esquerda. Arraste por ela para mudar a preferência. A conta no topo vem primeiro na regra **Minha preferência** e serve de desempate quando duas contas têm o mesmo custo. Pelo teclado, use as setas para cima e para baixo com a alça selecionada. ## Eventos do webhook Ao editar uma conta, a SuyPay mostra o endereço de avisos. Abra **Quais eventos configurar?** para ver os **nomes exatos dos eventos** separados por função: pagamentos, estornos, contestações e Pix Automático, quando disponíveis. Toque em um nome para copiá-lo, depois marque o evento no provedor. Na Efí, boleto e cartão recebem o endereço junto com cada cobrança; para Pix, cadastre o webhook da chave Pix. Cada grupo funciona de forma independente. Se você não configurar eventos de contestação, por exemplo, os avisos de pagamento configurados continuam chegando; a parte de contestações pode ficar sem atualização. A SuyPay também faz a [conferência](https://docs.suypay.com/reconciliation.md) das cobranças, mas ela não substitui todos os tipos de aviso. No celular, a lista de contas rola verticalmente. Toque e segure uma conta para revelar a alça; só a alça arrasta a conta, e ela permanece visível durante o movimento. Os formulários abrem como folhas com conteúdo rolável, agrupadas por tarefa, e os campos de taxa ficam em uma coluna para caber na tela. Na etapa de taxas, **Buscar taxas da conta** e **Preencher manualmente** ficam lado a lado; os valores importados podem ser conferidos antes de conectar. --- # Regras As regras decidem por qual conta cada venda passa. Sem nenhuma regra, a SuyPay sempre usa **a conta mais barata** e, se ela falhar, tenta a próxima. ## Como uma regra funciona Toda regra tem duas partes: **quando** ela vale e **o que** fazer. - **Quando:** forma de pagamento (Pix, boleto, cartão), faixa de valor e, se quiser, alguma informação sua da cobrança (`metadata`). - **O que fazer:** qual conta usar, entre as opções abaixo. As regras são lidas de cima para baixo, e a primeira que combinar com a venda é usada. | Usar | Como escolhe | |---|---| | **A mais barata** | Calcula a taxa de cada conta para aquele valor e usa a menor | | **Minha preferência** | Segue a ordem de preferência das contas | | **A mais estável agora** | Usa a que está aprovando mais e respondendo mais rápido | | **A que mais aprova cartão** | No cartão, usa a conta em que os bancos mais aprovaram os cartões dos seus clientes nos últimos 30 dias (contas novas começam em 80% até terem histórico). Pix e boleto vão para a mais barata | | **Sempre nesta ordem** | Usa exatamente as contas que você escolheu, na ordem escolhida | ## Exemplos - **Cartão sempre no Stripe:** quando for cartão, sempre nesta ordem: Stripe. - **Vendas grandes, conta estável:** a partir de R$ 1.000, a mais estável agora. - **Pedidos do app:** quando `canal = app`, minha preferência. ## Tentar outra conta se falhar Com essa opção ligada (o padrão), se a conta estiver fora do ar ou não responder, a venda passa para a próxima, sem o cliente perceber. Ela **não** troca de conta quando o banco recusa o cartão: outra conta recusaria do mesmo jeito. Se uma conta falhar três vezes seguidas, a SuyPay a pausa por um minuto e usa as outras. ## Testar antes Na página de Regras, use **Testar uma venda**: escolha a forma de pagamento e o valor, e veja qual conta seria usada, quanto ela cobraria e quais ficam de reserva. --- # Conferência Todo dia de madrugada, a SuyPay confere as vendas dos últimos dois dias com cada conta conectada. ## O que é conferido - **Situação:** se um aviso se perdeu e uma venda paga ainda aparece em aberto, a SuyPay corrige e manda o aviso que faltou. - **Taxa:** se a conta cobrou uma taxa diferente da que você cadastrou, a SuyPay passa a usar o valor real. - **Existência:** se a conta não encontra a venda, ela fica marcada para você olhar. No fim, você vê quanto cada conta vai pagar: vendido, taxas, devoluções e o valor a receber. ## Conferir agora Em **Conferência**, escolha o período e clique em **Conferir agora**. Pelo código: ```bash curl -X POST https://api.suypay.com/v1/reconciliation-runs \ -H "Authorization: Bearer suy_live_..." \ -H "Content-Type: application/json" \ -d '{ "start": "2026-10-01", "end": "2026-10-17" }' ``` --- # Proteção contra fraude O dinheiro não passa pela SuyPay: cada venda cai direto na conta que você conectou, e cada conta faz a própria verificação de identidade (KYC) e o próprio monitoramento. O que a SuyPay acrescenta é o que só ela vê: **o mesmo comprador, cartão ou rede em todas as suas contas ao mesmo tempo**. A Proteção roda antes de qualquer conta ser chamada. Uma venda barrada não chega a conta nenhuma: a cobrança volta com `status: "failed"`, `failure_code: "risk_blocked"` e o motivo em `failure_reason`. O comprador vê só "pagamento não concluído", nunca a regra que barrou. ## Sempre ligado Nas vendas reais, sem configurar nada: - **Teste de cartões.** Quem testa cartões roubados tenta muitos em sequência. Depois de **5 cartões recusados do mesmo IP em uma hora**, **5 do mesmo comprador no dia** ou **3 no mesmo link**, o cartão deixa de ser aceito ali. Pix e boleto continuam. - **Sinais.** A venda segue, mas fica marcada em **Proteção** e na cobrança (`risk`) quando: - o mesmo comprador tenta 6 cobranças ou mais em 24 horas; - o mesmo IP paga por 5 compradores diferentes ou mais no dia; - o mesmo comprador tenta 3 cartões diferentes ou mais no dia; - o valor passa de 10 vezes o valor mediano das suas vendas dos últimos 90 dias. Um sinal deixa a venda em **Atenção** (`elevated`); dois ou mais, em **Risco alto** (`high`). No modo de teste, a proteção contra teste de cartões fica desligada (é lá que você testa cartões recusados de propósito). Os seus limites e a lista de bloqueio valem nos dois modos, para você testar as regras. ## Antifraude das contas Cada conta tem a própria análise de risco, e o banco do comprador também. Elas aprovam mais quando sabem mais sobre quem compra. A SuyPay manda o que cada uma usa, sem você configurar nada: | Conta | O que vai junto do cartão | |---|---| | Mercado Pago | o **Device ID** (o script de segurança do Mercado Pago roda na página de pagamento e o valor vai no cabeçalho `X-meli-session-id`), o IP, o produto (`additional_info.items`) e os dados do comprador | | Pagar.me | o IP, o `session_id` da visita, o endereço de cobrança e o produto | | Asaas, Appmax | o IP do comprador e os dados do titular | | PagBank, TriboPay | os dados do titular, o endereço e o produto | | Stripe | o Radar da Stripe roda no Checkout dela | Pela API, mande `device` na cobrança (`user_agent`, `session_id` e `fingerprints`) e `customer.ip`. Uma venda que a análise da conta barra volta com `failure_code: "fraud_suspected"`. ## As suas regras Em **Recebimento › Proteção**, quem é dona ou admin define: | Regra | O que faz | |---|---| | Valor máximo por cobrança | recusa, já na criação, cobranças acima do valor | | Valor máximo por comprador, por dia | soma tudo o que o mesmo CPF/CNPJ (ou e-mail) tentou pagar em 24 horas | | Cobranças por comprador, por dia | quantas vezes o mesmo comprador pode tentar pagar em 24 horas | | Recusar vendas de risco alto | barra a venda quando dois ou mais sinais aparecem juntos, em vez de só marcar | | Lista de bloqueio | CPF/CNPJ, e-mail ou IP que não paga nenhuma cobrança da empresa | Da lista de bloqueio, a SuyPay guarda só uma impressão cifrada (HMAC) do valor e um trecho para você reconhecer (`•••.•••.789-09`). O CPF ou o e-mail em si não ficam salvos. ## Na cobrança Toda cobrança processada traz o campo `risk`: ```json "risk": { "level": "elevated", "flags": ["shared_ip"] } ``` | Sinal (`flags`) | Quer dizer | |---|---| | `payer_velocity` | o mesmo comprador tentou muitas cobranças em 24 horas | | `shared_ip` | o mesmo IP pagou por muitos compradores diferentes | | `many_cards` | o mesmo comprador tentou vários cartões | | `unusual_amount` | o valor está muito acima do que você costuma vender | Use isso no seu sistema para segurar a entrega de uma venda marcada até alguém conferir. ## Lavagem de dinheiro e uso proibido A SuyPay não aceita empresas que usam a plataforma para lavagem de dinheiro, fraude ou atividades proibidas nos [Termos de uso](https://www.suypay.com/termos). Quando a equipe confirma um caso, a empresa é **suspensa**: deixa de criar cobranças, saques, subcontas e chaves, e os links abertos param de aceitar pagamento. Ela continua vendo os dados, devolvendo dinheiro aos compradores e respondendo contestações. A SuyPay informa as autoridades quando a lei exige. --- # Webhooks Webhooks avisam o seu sistema quando algo acontece, como "pagamento recebido" ou "devolvido". Venha a venda de qual conta vier, o aviso tem sempre o mesmo formato. ## Adicionar um endereço Em **Webhooks → Adicionar endereço**, coloque a URL do seu sistema (precisa ser `https://`) e escolha os avisos que quer receber. ## Os avisos | Aviso | Quando | |---|---| | `payment.processing` | em análise (cartão), ainda sem resposta do banco | | `payment.succeeded` | o cliente pagou | | `payment.failed` | foi recusado | | `payment.attempt_failed` | uma tentativa no link de pagamento foi recusada (cartão negado, conta fora do ar) e o link voltou a aceitar pagamento; o motivo vem em `failure_code` e `last_error` | | `payment.created` | a cobrança foi criada | | `payment.canceled` | venceu ou você cancelou | | `payment.refunded` | devolvido por completo | | `payment.partially_refunded` | devolvido em parte | | `refund.created` | uma devolução foi pedida, ou feita direto no painel da conta | | `refund.updated` | a conta confirmou ou recusou uma devolução | | `reconciliation.completed` | a conferência do dia terminou | | `dispute.created` | o cliente contestou (MED ou chargeback) | | `dispute.updated` | a contestação mudou, por exemplo, você respondeu | | `dispute.closed` | a contestação terminou: ganha, perdida ou cancelada | | `subscription.created` | uma assinatura foi criada (Pix Automático: espera o cliente) | | `subscription.activated` | o cliente aprovou o Pix Automático, ou a cobrança no cartão foi aprovada (também quando sai de `past_due`) | | `subscription.refused` | o cliente não aprovou, o banco não confirmou, ou a primeira cobrança no cartão foi recusada | | `subscription.past_due` | cartão: os ciclos falharam em todas as tentativas | | `subscription.canceled` | a assinatura foi cancelada (por você ou pelo cliente) | | `subscription.expired` | chegou a data de fim | | `payout.created` | um [saque](https://docs.suypay.com/payouts.md) foi pedido | | `payout.updated` | o saque está a caminho, ou a conta ainda não confirmou (`uncertain: true`) | | `payout.paid` | o dinheiro chegou ao destino | | `payout.failed` | a conta recusou ou o banco devolveu; veja `failure_reason` | | `payout.canceled` | o saque foi cancelado antes de sair | | `subaccount.created` | uma subconta foi criada (pelo painel ou pela API). Se não reconhecer, confira em **Subcontas** | | `subaccount.updated` | a situação de uma subconta mudou: aprovada, recusada, bloqueada | | `payout_destination.created` | o dono salvou uma chave Pix para saques. Se não foi alguém da equipe, remova em **Saques** | ## O que chega ```json { "id": "evt_3Jd9...", "type": "payment.succeeded", "created": 1760000000, "data": { "object": { "id": "pay_...", "status": "succeeded", "amount": 4990, "fee": 49, "net": 4941 } } } ``` Responda com status `200` em até 8 segundos. Se o seu sistema não responder, a SuyPay tenta de novo depois de 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h. ## Confirmar que veio da SuyPay Todo aviso traz o cabeçalho `SuyPay-Signature`. Confira com a chave de assinatura do endereço: ```js import crypto from 'node:crypto' function veioDoSuyPay(corpo, cabecalho, chave) { const { t, v1 } = Object.fromEntries(cabecalho.split(',').map((p) => p.split('='))) const esperado = crypto.createHmac('sha256', chave).update(`${t}.${corpo}`).digest('hex') const recente = Math.abs(Date.now() / 1000 - Number(t)) < 300 return recente && crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(v1)) } ``` Use o corpo **exatamente como chegou**, antes de transformar em JSON. --- # UTMs e integrações Saiba qual anúncio trouxe cada venda. A SuyPay guarda as **UTMs** de cada cobrança e avisa as suas ferramentas de anúncio a cada mudança, seja qual for a conta que recebeu o dinheiro. ## UTMs na cobrança Mande `tracking` ao criar a cobrança: ```json { "method": "pix", "amount": 9700, "customer": { "name": "Ana Lima", "email": "ana@exemplo.com" }, "tracking": { "utm_source": "FB", "utm_campaign": "BLACK|1203", "utm_medium": "CONJUNTO|88", "utm_content": "VIDEO_2", "fbclid": "IwAR..." } } ``` | Campo | | |---|---| | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` | UTMs do anúncio | | `src`, `sck` | parâmetros de rastreio usados pela Utmify e por plataformas de infoproduto | | `fbclid`, `gclid`, `ttclid` | id do clique no anúncio (Meta, Google, TikTok) | | `fbp`, `fbc` | cookies `_fbp` e `_fbc` do pixel da Meta, quando você tem | | `ttp` | cookie `_ttp` do pixel do TikTok, quando você tem | Cada valor tem até 500 letras. A cobrança devolve o que foi guardado em `tracking`. ### No link de pagamento No anúncio, coloque as UTMs no próprio [link de pagamento](https://docs.suypay.com/payment-links.md): ``` https://checkout.SEU-DOMINIO/pay_3kXy...?t=...&utm_source=FB&utm_campaign=BLACK ``` Quando o cliente escolhe como pagar, a SuyPay guarda as UTMs do endereço, além do IP e do navegador dele, que as ferramentas usam para achar o clique. Se você mandou `tracking` ao criar o link, o que você mandou vale mais. ### Do seu site até o link Muitas vezes o anúncio leva o cliente para o **seu site**, e só depois ele clica no link de pagamento. Para as UTMs não se perderem no caminho, cole esta linha no `` do seu site (em **Integrações → UTMs do seu site** o painel mostra a linha pronta): ```html ``` O script: - guarda as UTMs e os ids de clique da visita no navegador do cliente, por 30 dias, só no seu site. Uma visita nova com UTMs troca as antigas (vale o último clique, como nas plataformas de anúncio); - coloca esses valores, mais os cookies `_fbp`, `_fbc` e `_ttp` dos pixels do seu site, em todo link para a página de pagamento da SuyPay, inclusive botões que aparecem depois; - não cria cookie e não manda nada para lugar nenhum: os valores só viajam no próprio link. Se o link já tem uma UTM, a do link vale. Para usar no seu código, por exemplo num redirecionamento: `SuyPay.withUtm(url)` devolve o endereço com as UTMs, e `SuyPay.utm()` devolve os valores. Com domínio de pagamento próprio, avise o script: `data-hosts="pagar.minhaloja.com"`. Para outro prazo, `data-days="7"`. Conte na política de privacidade do seu site que ele guarda a origem da visita para medir os anúncios. ### Nas assinaturas `tracking` na criação da assinatura vai para **todos os ciclos**, no Pix Automático e no cartão. ## Integrações Em **Integrações**, no painel, conecte a ferramenta e escolha se ela recebe vendas reais, de teste ou as duas. | Ferramenta | O que recebe | Quando | |---|---|---| | Utmify | o pedido com as UTMs, o valor, a taxa e o que sobra para você | ao gerar (Pix ou boleto esperando), ao aprovar, recusar, cancelar e devolver. Sempre o mesmo pedido, atualizado | | Meta (Facebook e Instagram) | uma compra no seu pixel, pela API de Conversões, com e-mail e celular cifrados | ao aprovar | | TikTok | uma compra (`CompletePayment`) no seu pixel, pela Events API, com e-mail e celular cifrados | ao aprovar | **Utmify:** gere a credencial em *Integrações › Webhooks › Credenciais de API*. Vendas de teste vão como teste e não aparecem nos relatórios. A Utmify pede o e-mail do cliente e não aceita vendas com mais de 7 dias (45 dias para devoluções). O que não cabe nisso aparece como "não enviado", com o motivo. **Meta:** no Gerenciador de Eventos, abra o pixel e vá em *Configurações › API de Conversões* para gerar o token. A compra vai com o id da cobrança como `event_id`. Se o seu site também dispara `Purchase` no navegador com o mesmo id, a Meta conta uma vez só. Para vendas de teste, informe o **código de teste** da aba *Eventos de teste*: sem ele, a SuyPay não envia, para não sujar os relatórios. **TikTok:** no TikTok Ads Manager, abra *Ferramentas › Gerenciador de eventos*, escolha o pixel e vá em *Configurações › Events API* para gerar o token. O código do pixel fica no topo da mesma página. A compra vai com o id da cobrança como `event_id`, com o `ttclid` do anúncio e o cookie `_ttp`, quando houver. Para vendas de teste, informe o **código de teste** da aba *Eventos de teste*. "Cifrados" quer dizer resumo SHA-256, que é o que a Meta e o TikTok pedem: eles comparam o resumo com os da própria base, sem receber o e-mail ou o celular em texto. ### Envios e novas tentativas Abra a integração para ver os últimos envios e a resposta da ferramenta. Se ela estiver fora do ar, a SuyPay tenta de novo em 1, 5 e 30 minutos, depois em 2, 6, 12 e 24 horas. Uma recusa por dado errado (4xx) não é repetida. **Enviar teste** manda a última venda aprovada como teste. As credenciais ficam criptografadas e não voltam pela API: aparecem só os 4 últimos caracteres. Pela API: `GET /v1/integration-kinds`, `GET/POST /v1/integrations`, `PATCH/DELETE /v1/integrations/{id}`, `GET /v1/integrations/{id}/deliveries` e `POST /v1/integrations/{id}/test`, com chave completa. --- # Bots de vendas (Discord e outros) Bots de vendas no Discord, no Telegram e no WhatsApp costumam pedir "o token do gateway" para gerar o Pix, esperar o pagamento e entregar o produto. A SuyPay foi pensada para esse uso: uma chave, um Pix, a imagem do QR Code e um aviso quando pagar, passando pela conta mais barata e seguindo por outra se uma cair. ## 1. Crie uma chave só para o bot Em **Desenvolvedores → Chaves e MCP → Criar chave**, escolha **Só cobranças**. Essa chave: - cria cobranças e vê **só as que ela mesma criou** (pelo id ou em `GET /v1/payments`, que lista só as dela); - **não** lista os seus clientes, **não** devolve dinheiro, **não** saca e **não** mexe em contas ou webhooks. Se o bot for de outra pessoa (um bot público ou comprado numa comunidade), use sempre essa chave. Se ela vazar, o pior que dá para fazer com ela é gerar cobranças **para você receber**. Revogue em um clique quando quiser. > **Atenção:** nunca cole uma chave **Completa** num bot de terceiros. E nunca cole as chaves do Mercado Pago, Asaas ou outra conta diretamente num bot: elas devolvem dinheiro e às vezes sacam. ## 2. Crie o Pix quando alguém comprar ```bash curl https://api.suypay.com/v1/payments \ -H "Authorization: Bearer suy_live_..." \ -H "Idempotency-Key: pedido-discord-81723" \ -H "Content-Type: application/json" \ -d '{ "method": "pix", "amount": 2990, "description": "VIP 30 dias", "customer": { "name": "fulano#1234" }, "expires_in_minutes": 30, "metadata": { "discord_user": "123456789012345678", "guild": "987654321", "produto": "vip-30" } }' ``` Use o id do pedido do bot na `Idempotency-Key`: se o bot repetir a chamada (queda, clique duplo), a SuyPay devolve o mesmo Pix em vez de criar outro. A resposta traz tudo que o bot mostra: | Campo | Para quê | |---|---| | `next_action.qr_code` | o Pix copia e cola (mande num bloco de código para copiar fácil) | | `next_action.qr_code_url` | a **imagem** do QR Code, pronta para `embed.image` no Discord | | `payment_url` | uma página de pagamento com QR Code e situação ao vivo | | `expires_at` | até quando o Pix vale | Se a venda precisar de CPF, e-mail ou celular para alguma conta, mande em `customer`. Sem eles, a SuyPay usa as contas que não pedem; se nenhuma servir, a resposta diz qual dado falta. ## 3. Saiba quando pagou O jeito certo é o [webhook](https://docs.suypay.com/webhooks.md): cadastre o endereço do bot, assine `payment.succeeded` e confira a assinatura `SuyPay-Signature`. Os `metadata` voltam no aviso, então o bot sabe quem comprou o quê. Tem mais de um bot na mesma empresa? Ao criar o endereço em **Webhooks**, escolha **Só da chave** do bot: cada um recebe apenas os avisos das cobranças que ele criou (`only_source: "key:key_..."` pela API). Se o bot não tiver um endereço público, consulte a cobrança a cada 5 a 10 segundos enquanto ela estiver aberta: ```bash curl https://api.suypay.com/v1/payments/pay_... -H "Authorization: Bearer suy_live_..." ``` Entregue o produto só com `status: "succeeded"`. Pare de consultar quando o status for `failed` ou `canceled` (venceu). ## Exemplo com discord.js ```js const suypay = (rota, corpo, chave) => fetch(`https://api.suypay.com/v1${rota}`, { method: corpo ? 'POST' : 'GET', headers: { Authorization: `Bearer ${process.env.SUYPAY_KEY}`, 'Content-Type': 'application/json', ...(chave ? { 'Idempotency-Key': chave } : {}), }, body: corpo && JSON.stringify(corpo), }).then((r) => r.json()) // dentro do comando /comprar const pedido = `${interaction.id}` const pix = await suypay('/payments', { method: 'pix', amount: 2990, description: 'VIP 30 dias', expires_in_minutes: 30, customer: { name: interaction.user.username }, metadata: { discord_user: interaction.user.id, produto: 'vip-30' }, }, pedido) if (pix.status === 'failed') return interaction.reply({ content: pix.failure_reason, ephemeral: true }) await interaction.reply({ ephemeral: true, content: 'Pix copia e cola:\n```' + pix.next_action.qr_code + '```', embeds: [{ title: 'Pague R$ 29,90 com Pix', image: { url: pix.next_action.qr_code_url }, url: pix.payment_url }], }) ``` ## Para quem vende bots Se você desenvolve um bot de vendas e quer oferecer a SuyPay como gateway, peça ao seu cliente só duas coisas: a chave **Só cobranças** e (opcional) o segredo do webhook. Funciona igual para todas as contas que ele conectar na SuyPay, e ele troca de conta sem mexer no bot. ## Erros comuns | Mensagem | O que fazer | |---|---| | `restricted_key` | a rota pede uma chave completa; bots só precisam criar e consultar cobranças | | `missing_document` / `missing_email` | peça o dado ao comprador ou conecte uma conta que não exige | | `Nenhuma conta conectada aceita Pix` | conecte uma conta no modo da chave (`suy_test_` usa contas de teste) | ## Um bot para várias empresas Se você desenvolve um bot que outras lojas usam, não peça a chave de cada uma. Crie um app em **Configuração → OAuth** e deixe cada loja autorizar o bot com um clique. Veja [OAuth para apps](https://docs.suypay.com/oauth.md). ## Bots com carteira (saldo) Muitos bots de vendas têm uma "carteira". Há dois tipos, e a SuyPay atende os dois: **Saldo do comprador** (ele recarrega e depois gasta no bot): a recarga é uma cobrança Pix normal com `metadata` como `{ "tipo": "recarga", "discord_user": "..." }`. Quando chegar `payment.succeeded`, o bot soma o valor no saldo que ele mesmo guarda. Use o id do evento para não somar duas vezes. Funciona com a chave **Só cobranças**. **Saldo do vendedor** (um bot com vários vendedores, e o dono do bot fica com uma comissão): cada vendedor vira uma [subconta](https://docs.suypay.com/subaccounts.md) e cada venda manda a parte dele com `splits`. O dinheiro fica na conta de pagamento, não no bot: 1. Conecte uma conta que tenha subcontas (Pagar.me, Asaas, Woovi, Wyvi Pay ou Pagmaster). 2. Ao cadastrar um vendedor, crie a subconta (`POST /v1/subaccounts`) e guarde o `id` dele no bot. Dá para guardar o id do Discord em `metadata`. 3. Em cada venda, mande `splits: [{ "subaccount_id": "sub_...", "percentage": 90 }]`. A conta principal fica com o resto e paga as taxas. 4. O saldo do vendedor é `GET /v1/subaccounts/:id/balance`, e o saque (`POST /v1/subaccounts/:id/withdrawals`) só vai para a chave Pix dele, salva na criação. Isso exige uma chave **Completa**, guardada só no servidor do dono do bot: chaves **Só cobranças** não dividem vendas, porque split é dinheiro indo para outra pessoa. Não use os saques normais para pagar vendedores: eles só vão para as chaves Pix salvas da sua empresa. --- # OAuth para apps Se você faz um bot, plugin ou sistema que **várias empresas** usam, não peça a chave de API de cada uma. Com OAuth, a loja clica em **Autorizar**, escolhe a empresa e o que o app pode fazer, e o seu app recebe um token só para isso. A loja tira o acesso quando quiser, em **Configuração → OAuth**. Para um bot que só você usa, na sua própria empresa, uma [chave restrita](https://docs.suypay.com/bots.md) basta. ## Como funciona 1. O seu app manda a pessoa para `https://oauth.suypay.com/authorize`. 2. Ela entra com o GitHub, vê o nome do app, quem o fez e o que ele vai poder fazer, escolhe a empresa e autoriza. Só a dona ou um admin da empresa autoriza apps. 3. A SuyPay volta para o endereço de retorno do app com um `code`. 4. O app troca o `code` por um `access_token` (vale 1 hora) e um `refresh_token`. 5. O app chama a API normalmente, com `Authorization: Bearer suy_oat_...`. ## Criar o app Em **Configuração → OAuth → Criar app**, informe: | Campo | O que é | |---|---| | Nome, descrição e site | o que a loja vê na hora de autorizar | | Endereços de retorno | para onde a SuyPay volta depois da autorização. Precisa ser **igual** ao `redirect_uri` enviado, caractere por caractere. `https://`, ou `http://` só para `localhost` | | O que o app pode pedir | as permissões abaixo | | Onde o app roda | **Servidor** (tem `client_secret`) ou **Aparelho** (app, extensão, CLI: sem segredo) | | Webhook do app | um endereço para receber os avisos de todas as empresas que autorizaram | Você recebe o `client_id` (`app_...`) e, no tipo Servidor, o `client_secret` (`suy_cs_...`), mostrado **uma única vez**. Dá para trocar o segredo depois. ## Permissões | `scope` | O app pode | |---|---| | `charges` | criar cobranças (Pix, boleto, cartão), cancelar, simular no modo de teste e consultar **só as cobranças que ele criou** | | `payments.read` | ver todas as vendas e clientes da empresa | | `refunds` | devolver pagamentos | Nenhum app vê as chaves das contas conectadas, mexe em contas e regras, faz saques ou divide vendas com subcontas. ## 1. Mandar a pessoa autorizar Gere um `code_verifier` aleatório (43 a 128 caracteres) e o `code_challenge`, que é o SHA-256 dele em base64url. O PKCE é **obrigatório** para todo app, mesmo os de servidor. ```text https://oauth.suypay.com/authorize ?response_type=code &client_id=app_... &redirect_uri=https://meubot.com/suypay/callback &scope=charges &state=um-valor-aleatorio-seu &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM &code_challenge_method=S256 ``` Guarde o `state` e confira que ele volta igual: é o que impede alguém de colar um código de outra pessoa no seu app. Na volta, a SuyPay chama o seu endereço com `?code=...&state=...&iss=https://oauth.suypay.com`. Se a pessoa cancelar, vem `?error=access_denied&state=...`. ## 2. Trocar o código pelo token O código vale **2 minutos** e funciona uma vez só. Se o mesmo código for usado de novo, a SuyPay entende que ele vazou e cancela os tokens que saíram dele. ```bash curl https://api.suypay.com/oauth/token \ -u "app_...:suy_cs_..." \ -d grant_type=authorization_code \ -d code=O_CODIGO \ -d redirect_uri=https://meubot.com/suypay/callback \ -d code_verifier=O_VERIFIER ``` Apps do tipo Aparelho mandam `client_id` no corpo em vez do `-u`. ```json { "access_token": "suy_oat_...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "suy_ort_...", "scope": "charges", "modes": ["test", "live"], "organization": { "id": "org_...", "name": "Loja da Maria" } } ``` Guarde o `organization.id`: é a empresa daquele token. Um app autorizado por várias empresas tem um par de tokens para cada uma. ## 3. Usar a API ```bash curl https://api.suypay.com/v1/payments \ -H "Authorization: Bearer suy_oat_..." \ -H "SuyPay-Mode: live" \ -H "Idempotency-Key: pedido-81723" \ -H "Content-Type: application/json" \ -d '{ "method": "pix", "amount": 2990, "customer": { "name": "Fulano" } }' ``` `SuyPay-Mode` escolhe entre dados reais (`live`) e de teste (`test`), dentro do que a empresa liberou (`modes`). Sem o cabeçalho, vale `live` quando a empresa liberou dados reais. O mesmo token funciona no [servidor MCP](https://docs.suypay.com/mcp.md). ## 4. Renovar o token ```bash curl https://api.suypay.com/oauth/token \ -u "app_...:suy_cs_..." \ -d grant_type=refresh_token \ -d refresh_token=suy_ort_... ``` A resposta traz um `access_token` **e um `refresh_token` novos**; o anterior deixa de valer na hora. Se um `refresh_token` já usado aparecer de novo, a SuyPay entende que ele foi copiado e cancela todos os tokens daquela autorização: a empresa precisa autorizar de novo. Por isso, guarde sempre o último e renove um de cada vez. O `refresh_token` vale 90 dias sem uso. ## Taxa do app O seu app pode ficar com uma parte de cada venda que ele criar, como numa plataforma: **um valor fixo, um percentual ou os dois** (até 20%). Configure em **Desenvolvedores › OAuth › Seus apps**, em *Cobrar uma taxa por venda*. - A empresa vê a taxa na página de autorização, antes de aprovar, e em cada pagamento, na parte de valores. - A taxa sai da venda pela própria conta da empresa, para você. A SuyPay não segura o dinheiro. Ela chega de um destes jeitos, conforme a conta que recebeu a venda: | Conta da empresa | Como a taxa chega | O que você informa | |---|---|---| | Asaas | **Split** da venda, direto para a sua carteira | `walletId` da sua conta Asaas | | Efí (Pix) | **Split** do Pix, direto para a sua conta Efí | CPF ou CNPJ e número da conta: `12345678909:1234567` | | WyviPay, Pagmaster, InvictusPay, ClownPay | **Pix** da conta da empresa para a sua chave, assim que a venda é paga | Sua chave Pix | - O Pix da taxa aparece nos **Saques** da empresa, marcado como taxa do app. Se a conta ainda não tem o dinheiro disponível (cartão que cai depois), a SuyPay tenta de novo uma vez por dia, por até 30 dias. Uma devolução depois do Pix enviado não traz a taxa de volta. - A Efí só divide Pix com o escopo `gn.split.write` ligado na aplicação da empresa, e não devolve um Pix que foi dividido. - No modo de teste, qualquer venda pelo sandbox já registra a taxa, para você testar sem configurar nada. - **Só vender por contas que repassam a taxa** (ligado por padrão): a venda do app passa só pelas contas da empresa que conseguem dividir ou mandar a taxa por Pix; se nenhuma conseguir, a cobrança não é criada. Desligado, ela segue sem a taxa e o pagamento mostra `application_fee.status = "skipped"`. - Vendas que a empresa cria no painel ou com a chave dela não pagam a taxa do app. Quem já autorizou continua com a taxa que aceitou. Se você **aumentar** a taxa, ela só vale para quem autorizar de novo; uma **redução** vale na hora. Numa venda, o app pode cobrar menos (nunca mais) com `application_fee_amount`, em centavos: ```http POST /v1/payments Authorization: Bearer suy_oat_... { "method": "pix", "amount": 10000, "customer": { ... }, "application_fee_amount": 150 } ``` Cada pagamento traz a taxa: ```json "application_fee": { "app": "app_...", "app_name": "Bot de Vendas", "amount": 250, "status": "collected", "provider": "asaas", "via": "split", "payout": null, "skipped_reason": null } ``` `via`: `split` (dividida na venda) ou `pix` (enviada por Pix depois; `payout` é o saque da empresa que levou a taxa). `status`: `pending` (a venda ainda não foi paga, ou o Pix da taxa ainda não saiu), `collected` (a sua parte foi dividida ou o Pix chegou), `refunded` (venda devolvida inteira), `canceled` (venda não concluída) e `skipped` (a conta não dividia). O resumo dos últimos 30 dias, por empresa, fica no próprio app em **Seus apps**. > Para quem gerencia os próprios vendedores pela API (marketplace com subcontas), a mesma ideia já existe com `splits`: cada vendedor recebe a parte dele e a sua conta fica com o resto. Veja [Subcontas e split](https://docs.suypay.com/subaccounts.md). ## Revogar Quando a loja desinstala o seu app, revogue: ```bash curl https://api.suypay.com/oauth/revoke -u "app_...:suy_cs_..." -d token=suy_ort_... ``` A loja também tira o acesso em **Configuração → OAuth**. A partir daí, a API responde `401` para os tokens daquela empresa. ## Webhook do app Com o webhook do app cadastrado, cada empresa que autoriza passa a mandar os avisos para ele, assinados com o segredo do app (`SuyPay-Signature`, igual aos [webhooks](https://docs.suypay.com/webhooks.md)). Cada aviso diz de qual empresa é: ```json { "id": "evt_...", "object": "event", "type": "payment.succeeded", "organization": "org_...", "data": { "object": { "id": "pay_...", "status": "succeeded" } } } ``` Com só `charges`, chegam apenas os avisos das cobranças que o app criou. Com `payments.read`, os de todas as vendas da empresa. ## Erros | Onde | `error` | Quer dizer | |---|---|---| | retorno da autorização | `access_denied` | a pessoa cancelou | | retorno da autorização | `invalid_scope` | o app pediu uma permissão que não tem cadastrada | | retorno da autorização | `invalid_request` | faltou `state` ou PKCE (`code_challenge` com `S256`) | | `/oauth/token` | `invalid_client` | `client_id` ou `client_secret` errado, ou app desativado | | `/oauth/token` | `invalid_grant` | código vencido, já usado, de outro app, `redirect_uri` ou `code_verifier` diferente, ou `refresh_token` já usado | | API | `401` | token vencido ou revogado: renove com o `refresh_token` | | API | `403` `insufficient_scope` | o app não tem permissão para essa rota | Um `client_id` ou endereço de retorno errado **não volta para o app**: a página de autorização mostra o erro para a pessoa, para ninguém usar a SuyPay como desvio para outro site. ## Descoberta automática Clientes que leem os metadados do servidor de autorização (como alguns clientes MCP) encontram tudo em `https://www.suypay.com/.well-known/oauth-authorization-server`. --- # Use com IA A SuyPay funciona com as ferramentas de IA que você já usa para programar e criar apps: Claude, Codex, ChatGPT, Lovable, Cursor, GitHub Copilot, Windsurf, Gemini, v0, Bolt e Replit. Escolha a sua abaixo e copie a configuração. ## Docs que a IA lê Toda a documentação existe em texto puro, no formato que os assistentes leem melhor ([llms.txt](https://llmstxt.org)): | Endereço | O que tem | |---|---| | [`/llms.txt`](/llms.txt) | o índice: cada página com uma linha dizendo o que ela ensina | | [`/llms-full.txt`](/llms-full.txt) | todas as páginas num arquivo só, para anexar numa conversa | | `/.md` | uma página em Markdown, como [`/payments.md`](/payments.md) | | [`/openapi.json`](https://api.suypay.com/openapi.json) | todas as rotas da API, para gerar cliente ou validar chamadas | No topo de cada página, **Copiar página** copia o texto em Markdown, e a setinha ao lado abre a página no ChatGPT ou no Claude. ## Conectar pelo MCP Assistentes de código (Claude Code, Codex, Cursor, Copilot, Windsurf, Gemini) conectam no servidor MCP da SuyPay e passam a criar cobranças, ver vendas, responder contestações e registrar entregas conversando. As ferramentas estão em [Usar com IA (MCP)](https://docs.suypay.com/mcp.md). - **Endereço:** `https://api.suypay.com/mcp` - **Cabeçalho:** `Authorization: Bearer suy_test_...` > **Atenção:** guarde a chave numa variável de ambiente (`SUYPAY_KEY`), nunca dentro do código nem num arquivo que vai para o Git. Comece pela chave de teste: com a real, o assistente move dinheiro de verdade. ## Apps criados por IA Lovable, v0, Bolt e Replit escrevem o app inteiro. Dê o pedido abaixo para eles e confira três coisas no que gerarem: 1. **A chave só no servidor.** A chamada para a SuyPay fica numa função do servidor (Edge Function, rota de API), com a chave nos segredos do projeto. Se a chave aparecer no código do navegador, qualquer visitante consegue usar. 2. **O pago vem do webhook.** O app libera o pedido quando chega `payment.succeeded` no [webhook](https://docs.suypay.com/webhooks.md), com a assinatura conferida. Nunca porque a tela de obrigado abriu. 3. **Valores em centavos.** R$ 49,90 é `4990`. ```text Leia https://docs.suypay.com/llms.txt e integre a SuyPay neste projeto. - Chame a API só do lado do servidor, com a chave em SUYPAY_KEY. Nunca no navegador. - Valores em centavos. Crie a cobrança com POST /v1/payments e mande o cliente para payment_url. - Confirme o pagamento pelo webhook payment.succeeded (confira a assinatura), não pela tela. - Comece com uma chave de teste (suy_test_...). ``` ## Por que funciona bem com IA - **Erros em português, com código.** Cada erro diz o que fazer e traz um código estável (`missing_document`, `amount_too_low`), então o assistente corrige sozinho. Veja [Erros](https://docs.suypay.com/errors.md). - **Uma API só para todas as contas.** O mesmo `POST /v1/payments` serve Mercado Pago, Asaas, Efí, Stripe e as outras: a IA não precisa aprender cada uma. - **Modo de teste completo.** A conta de teste confirma pagamentos e abre contestações de mentira, para a IA testar o fluxo inteiro sem dinheiro real. Veja [Modo de teste](https://docs.suypay.com/testing.md). --- # Usar com IA (MCP) A SuyPay tem um servidor MCP: conecte num assistente de IA que aceite MCP e peça as coisas em português. - "Cria um Pix de R$ 49,90 para a Maria Silva e me manda o link" - "Quanto eu vendi essa semana, por conta?" - "Cria um Pix Automático mensal de R$ 99 para a Ana, CPF 529.982.247-25" - "Tem alguma contestação para responder?" ## Conectar Crie uma chave em **Desenvolvedores → Chaves e MCP**. Comece por uma chave de teste. Depois, no seu assistente, adicione um servidor MCP com: - **Endereço:** `https://api.suypay.com/mcp` - **Cabeçalho:** `Authorization: Bearer suy_test_...` (ou o token de um [app OAuth](https://docs.suypay.com/oauth.md), `suy_oat_...`, que só vê as ferramentas das permissões aprovadas) A maioria dos apps aceita este formato: ```json { "mcpServers": { "suypay": { "type": "http", "url": "https://api.suypay.com/mcp", "headers": { "Authorization": "Bearer suy_test_..." } } } } ``` Em apps de linha de comando, costuma ser assim: ```bash claude mcp add --transport http suypay https://api.suypay.com/mcp \ --header "Authorization: Bearer suy_test_..." ``` ## Ferramentas | Ferramenta | | |---|---| | `create_payment` | criar Pix, boleto ou cartão (devolve o link de pagamento) | | `get_payment` | ver uma cobrança e por onde ela passou | | `simulate_test_payment` | confirmar uma cobrança da conta de teste da SuyPay, do Asaas sandbox ou do Inter sandbox; exige chave de teste | | `list_payments` | listar cobranças | | `refund_payment` | devolver dinheiro | | `create_pix_automatic` | criar um Pix Automático e o QR Code de aprovação | | `list_pix_automatic` / `get_pix_automatic` | ver os Pix Automáticos e os ciclos | | `charge_pix_automatic` | cobrar um ciclo (valor variável) | | `cancel_pix_automatic` | cancelar um Pix Automático | | `list_disputes` | ver MED e chargebacks, com prazo | | `submit_dispute_evidence` | responder uma contestação (Stripe e Woovi) | | `record_fulfillment` | registrar a entrega de uma venda (rastreio, acessos, nota): a prova que mais pesa numa contestação | | `list_providers` | ver as contas conectadas e as taxas | | `simulate_routing` | ver por qual conta uma venda passaria | | `get_overview` | resumo de vendas, taxas e valor a receber | | `run_reconciliation` | conferir as vendas com as contas | Os erros chegam em português, com o código do motivo (por exemplo `[missing_document]`), então o assistente sabe o que pedir para você. > **Atenção:** com uma chave real, o assistente pode devolver dinheiro, cancelar Pix Automático e responder contestações de verdade. A SuyPay pede para ele confirmar com você antes, mas prefira chaves de teste para explorar. --- # Empresas e equipe ## Entrar O acesso é sempre pela conta do GitHub. No primeiro acesso, a SuyPay cria uma empresa para você. ## O endereço da empresa Cada empresa tem um endereço próprio no painel: `dash.suypay.com/loja-da-maria`. Ele aparece no navegador e nos links que você manda para a equipe, então um link sempre abre a empresa certa, mesmo com duas abas abertas em empresas diferentes. Duas empresas podem ter o mesmo nome; o endereço nunca se repete (`loja-da-maria`, `loja-da-maria-2`). Quando você participa de duas com o mesmo nome, o seletor mostra o endereço embaixo de cada uma. Para trocar o endereço, vá em **Configuração → Geral**. Links antigos param de abrir a empresa. ## Convidar pessoas Em **Configuração → Equipe → Convidar**, escolha: - **Como a pessoa entra:** o cargo dela (veja abaixo); - **Por quanto tempo o link vale:** 1, 7 ou 30 dias; - **Quantas pessoas podem usar:** uma só ou sem limite. Mande o link por onde quiser. Quem abrir entra com o GitHub e já cai na sua empresa. Dá para cancelar um link a qualquer momento. ## Cargos | | Dona | Admin | Financeiro | Desenvolvedor | Vendedor | Leitura | |---|---|---|---|---|---|---| | Ver vendas e clientes | sim | sim | sim | sim | sim | sim | | Criar cobranças | sim | sim | sim | sim | sim | não | | Devolver dinheiro | sim | sim | sim | não | não | não | | Responder contestações | sim | sim | sim | não | não | não | | Ver saques e subcontas | sim | sim | sim | não | não | sim | | Fazer saques | sim | sim | sim | não | não | não | | Escolher as chaves Pix que recebem saques | sim | não | não | não | não | não | | Conectar contas e mudar regras | sim | sim | não | não | não | não | | Chaves de API, webhooks e apps OAuth | sim | sim | não | sim | não | não | | Autorizar apps de terceiros | sim | sim | não | não | não | não | | Convidar pessoas e mudar cargos | sim | sim | não | não | não | não | O cargo vale para tudo: o painel esconde o que a pessoa não pode, e a API recusa do mesmo jeito. - **Admin** só é dado ou tirado pela dona. Um admin não promove outra pessoa a admin nem remove um admin. - **Dona** é uma por empresa. Para passar a empresa para outra pessoa, use **Transferir empresa** em Equipe: ela vira dona e você vira admin. - Qualquer pessoa, menos a dona, pode **sair da empresa** em Configuração → Geral. ## Várias empresas Atende mais de um cliente? Crie uma empresa para cada um, pelo seletor no topo do menu. Cada empresa tem as próprias contas, vendas, chaves e equipe, sem nenhuma mistura. Trocar de empresa mantém a tela em que você está. --- # Apps da SuyPay O app da SuyPay para Android e iPhone abre o mesmo painel do navegador e avisa cada venda na hora, com som, mesmo com o celular bloqueado. No **Windows** e no **Linux** (Ubuntu e outros), o app do computador faz o mesmo com as notificações do sistema. ## Instalar 1. Instale o app **SuyPay** no Android ou no iPhone. 2. Toque em **Continuar com GitHub**: o login abre no navegador do celular (Chrome no Android, Safari no iPhone), com as senhas que ele já guarda, e volta sozinho para o app. Se o navegador não voltar sozinho (acontece quando o GitHub aprova sem você tocar em nada), toque em **Abrir o app SuyPay** na página que aparece. 3. Quando o app pedir, **permita as notificações**. Pronto: a próxima venda aprovada aparece no celular. ## O que o celular avisa Por padrão, o que pede atenção: **venda aprovada**, **nova contestação** (MED ou chargeback), **contestação encerrada** (ganha ou perdida), **saque não concluído**, **assinatura atrasada no cartão** e **cobrança barrada pela Proteção**. Você muda isso em **Configuração › Geral › Notificações**, para cada aparelho: - quais avisos chegam: também **devolução feita** (inteira ou parcial), **saque pago**, **nova assinatura** e **assinatura cancelada**; - se as vendas do **modo de teste** também avisam (ligado em aparelhos novos, com “Teste” no começo; no Android, num canal só delas); - se uma empresa fica em silêncio, quando você participa de mais de uma. No Android os avisos chegam em três canais, que você pode silenciar separadamente nos ajustes do celular: **Vendas**, **Avisos importantes** e **Movimentações**. Tocar na notificação abre a cobrança no app, já na empresa e no modo certos. **Enviar teste** manda uma notificação na hora para conferir. Com o painel aberto, o mesmo aviso aparece no canto da tela, uma vez só, e só se for da empresa e do modo que você está vendo. As notificações são de cada pessoa: cada uma da equipe escolhe as dela. Só recebe quem pode ver os pagamentos da empresa (e os saques, para os avisos de saque). ## No computador 1. Baixe o app em **suypay.com** (Windows ou Linux) e entre com a sua conta: o login abre no navegador e volta para o app. 2. O computador entra sozinho em **Configuração › Geral › Notificações**, com os mesmos avisos do celular. **Parar** neste computador desliga até você tocar em **Ligar neste computador**. As notificações aparecem na central do Windows e nos avisos do Ubuntu (GNOME), mesmo com a janela escondida. Clicar abre a cobrança na empresa e no modo certos. Ao fechar a janela, o app continua perto do relógio e segue avisando; pelo ícone dá para sair de vez, desligar isso ou abrir o app junto com o computador. Avisos que chegaram com o computador desligado ou dormindo aparecem quando ele volta, se for na mesma hora. ## Links fora do painel O app é só o painel. A documentação, o site e as páginas de pagamento abrem no navegador do celular, por cima do app; ao fechar, você volta para onde estava. ## Privacidade A notificação mostra o valor, a forma de pagamento e só o **primeiro nome** do comprador, porque a tela bloqueada fica à vista de quem está perto. Ao sair da conta no app, o celular para de receber na hora. --- # Segurança e privacidade O que a SuyPay faz para proteger os seus dados, os dos seus clientes e os cartões, e o que fica com você. A [política de privacidade](https://www.suypay.com/privacidade) e os [termos de uso](https://www.suypay.com/termos) dizem o mesmo em linguagem de contrato. ## Cartões O número do cartão **nunca passa pelo seu site, pelo painel nem pela API da SuyPay**. Ele entra e sai só pelo cofre de cartões, um sistema à parte, com banco e chaves próprios, que segue o PCI DSS. ``` navegador do cliente ── quadro do cofre ──► token tok_… (o número entra aqui) API da SuyPay ── pedido assinado ─────────► cofre ──► conta (o número sai só aqui) ``` | | Como é feito | |---|---| | Criptografia | AES-256-GCM, com uma chave de dados por empresa e modo. Cada cartão fica preso à empresa e ao próprio id: copiado para outro lugar, não abre. | | Chave mestra | Protege as chaves de dados e só abre com duas metades guardadas por pessoas diferentes. Nenhuma metade sozinha diz nada. Pode ser trocada sem recifrar os cartões. | | CVV | Apagado na primeira aprovação ou uma hora depois de digitado, o que vier primeiro. | | O que você vê | Bandeira, 6 primeiros e 4 últimos dígitos, validade e uma impressão digital (HMAC com chave) para achar cartões repetidos. | | Saída do número | Só para a API da conta de pagamento, numa lista fechada de endereços `https`, sem seguir redirecionamentos. Se a conta devolver o número na resposta, o cofre o apaga antes de responder. | | API ↔ cofre | Cada pedido e cada resposta são assinados (Ed25519) e valem uma vez só, por 5 minutos. | | Trilha | Todo acesso a cartão fica registrado por 400 dias: quem, o quê, de onde e se deu certo. Nunca o cartão. | | Campos no navegador | Página isolada, com CSP de nonce. Os tokens têm limite por IP e por chave. Em [Só nos seus sites](https://docs.suypay.com/cards.md#so-nos-seus-sites) você trava os campos aos seus domínios. | Com isso, o seu site fica no **SAQ A**, o nível mais simples do PCI DSS: você só mostra o quadro. ## Chaves e segredos - **Chaves das contas conectadas, segredos de webhook, credenciais de integrações e o que as contas devolvem para cobrar um cartão de novo** são guardados com AES-256-GCM, cada valor preso à própria linha. Nada disso volta pela API: aparecem só os últimos caracteres. - **Chaves de API** da SuyPay são guardadas só como resumo (SHA-256). Se você perder uma, crie outra; ninguém consegue lê-la de volta. - **Chaves "só cobranças"** criam cobranças e veem só as delas. Use em bots, plugins e sistemas de terceiros. Cobrar cartão salvo sem o cliente presente exige chave completa. - **Limite de uso:** cada chave tem um limite de requisições por segundo; quem passa recebe `429`. ## Avisos - **O que a SuyPay manda para você** vem com o cabeçalho `SuyPay-Signature`, um HMAC-SHA256 com o segredo do endereço e a hora do envio. Confira antes de confiar ([Webhooks](https://docs.suypay.com/webhooks.md)). - **O que as contas mandam para a SuyPay** chega num endereço com um token só daquela conta, e a SuyPay sempre lê a cobrança de volta na API da conta antes de mudar qualquer coisa. Um aviso falso não marca nada como pago. ## Painel e equipe - Login pelo GitHub. A sessão fica num cookie `HttpOnly`, `Secure` e `SameSite=Lax`. - Cada pessoa tem um cargo, e cada rota da API diz qual permissão exige. Uma rota nova fica fechada até alguém decidir quem pode usá-la. - Apps de terceiros entram por [OAuth](https://docs.suypay.com/oauth.md), com permissões e modos que você escolhe e tira quando quiser. ## Dados dos clientes - A SuyPay guarda só o que a cobrança precisa: nome, CPF ou CNPJ, e-mail, celular e endereço quando a conta pede, mais a origem da venda ([UTMs](https://docs.suypay.com/integrations.md)) e o IP de quem pagou pela página da SuyPay. - Para os dados dos seus clientes, **você é o controlador** e a SuyPay é a operadora (LGPD). Conte aos seus clientes, na sua política, que a venda passa pela SuyPay e pelas contas de pagamento, e quais ferramentas de anúncio você liga. - Para a Meta e o TikTok, e-mail, celular e id do cliente vão como resumo SHA-256, como eles pedem. ## Fraude e lavagem de dinheiro - Toda venda passa pela [Proteção](https://docs.suypay.com/protection.md) antes de chegar a uma conta: teste de cartões é cortado sozinho, e você define limites e uma lista de bloqueio. - Os valores da lista de bloqueio ficam só como impressão cifrada (HMAC). - Uso para fraude ou lavagem confirmado suspende a empresa: ela para de cobrar e sacar, e as autoridades são informadas quando a lei exige. ## O que fica com você - Guarde as chaves de API só no seu servidor e revogue na hora qualquer uma exposta. - Confira a assinatura dos webhooks. - Trave os campos de cartão aos seus domínios. - Dê a cada pessoa da equipe só o cargo que ela precisa. ## Encontrou uma falha? Escreva para **seguranca@suypay.com** antes de divulgar, com os passos para reproduzir. Não processamos quem testa de boa-fé, sem acessar dados de outras pessoas e sem prejudicar o serviço. --- # Visão geral da API A API da SuyPay segue REST: endereços previsíveis, corpo em JSON e códigos HTTP comuns. Tudo o que o painel faz, a API também faz. ```bash https://api.suypay.com/v1 ``` A especificação completa em OpenAPI, para gerar clientes automaticamente, fica em [`https://api.suypay.com/openapi.json`](https://api.suypay.com/openapi.json). ## Autenticação Crie uma chave em **Desenvolvedores → Chaves e MCP**, no painel, e mande no cabeçalho `Authorization`: ```bash Authorization: Bearer suy_test_... ``` Chaves `suy_test_` usam o modo de teste, e chaves `suy_live_`, o modo real. A chave já diz qual é a empresa. Chaves `glk_` criadas antes da mudança de nome (a SuyPay se chamava Glok) continuam valendo. Toda chave tem um acesso: | Acesso | Pode | Use em | |---|---|---| | **Completa** | tudo da API (saques só se ligados em **Saques → Segurança**) | o seu próprio servidor | | **Só cobranças** | `POST /payments`, `GET /payments/:id`, `POST /payments/:id/cancel` e `/sync` | bots de vendas, plugins, sistemas de terceiros ([veja o guia](https://docs.suypay.com/bots.md)) | Uma chave **Só cobranças** recebe `403` com `code: "restricted_key"` nas outras rotas. ## Valores Valores são sempre em **centavos**, em reais: `4990` é R$ 49,90. ## Sem cobrança em dobro Mande um `Idempotency-Key` ao criar cobranças. Se a mesma chamada chegar duas vezes, a SuyPay devolve a cobrança que já criou em vez de cobrar de novo. ## Listas e páginas Listas vêm como `{ "data": [...], "has_more": true }`. Para a próxima página, use `?starting_after=<último id>`. ## Exemplo em Node.js ```js const suypay = (rota, corpo) => fetch(`https://api.suypay.com/v1${rota}`, { method: corpo ? 'POST' : 'GET', headers: { Authorization: `Bearer ${process.env.SUYPAY_KEY}`, 'Content-Type': 'application/json', }, body: corpo && JSON.stringify(corpo), }).then((r) => r.json()) const venda = await suypay('/payments', { method: 'pix', amount: 4990, customer: { name: 'Maria Silva' }, }) console.log(venda.next_action.qr_code) ``` ## Recursos | Recurso | O que tem | |---|---| | [Cobranças](https://docs.suypay.com/api-payments.md) | criar, listar, devolver, sincronizar e simular | | [Contas e regras](https://docs.suypay.com/api-accounts.md) | conectar contas e decidir o caminho de cada venda | | [Saques](https://docs.suypay.com/api-payouts.md) | saldo das contas, saques e chaves Pix salvas | | [Avisos e relatórios](https://docs.suypay.com/api-events.md) | eventos, webhooks, resumo e conferência | | [Erros](https://docs.suypay.com/errors.md) | o que cada código quer dizer | --- # Erros Quando algo dá errado, a resposta explica o quê: ```json { "error": { "type": "invalid_request", "message": "Esse CPF ou CNPJ não é válido. Confira os números.", "param": "customer.document" } } ``` A `message` está sempre em português e diz o que fazer, então dá para mostrar direto para quem está usando o seu sistema. | Código | Quer dizer | |---|---| | `400` | falta um campo ou ele está errado (veja `param`) | | `401` | chave inválida ou revogada | | `403` | essa chave ou pessoa não pode fazer isso (veja `code`: `restricted_key`, `payouts_api_disabled`) | | `404` | não existe, ou é de outra empresa | | `409` | essa cobrança já está sendo criada (mesma `Idempotency-Key`) | | `422` | não conseguimos entrar na conta conectada: confira as chaves | | `429` | muitas chamadas seguidas. Espere alguns segundos | | `5xx` | erro nosso. Tente de novo | > **Dica:** uma cobrança recusada **não** é erro. Você recebe a cobrança com `status: "failed"`, o motivo em `failure_reason` (para mostrar) e um código em `failure_code` (para o seu sistema decidir o que fazer). Num link de pagamento, a cobrança recusada volta a aceitar pagamento (`status: "requires_method"`) e traz `last_error`: `{ "method": "card", "code": "card_declined", "message": "O banco não aprovou o cartão. Tente outro cartão ou pague com Pix.", "at": "..." }`. A `message` de `last_error` é a que o comprador vê: nunca diz qual verificação falhou, para não ajudar quem testa cartões roubados. ## Motivos (`failure_code` e `error.code`) São os mesmos para todas as contas. A SuyPay traduz o erro de cada uma para esta lista. | Código | Quer dizer | O que fazer | |---|---|---| | `card_declined` | o banco recusou o cartão | pedir outro cartão ou Pix | | `insufficient_funds` | sem limite | pedir outro cartão ou Pix | | `card_expired` | cartão vencido | pedir outro cartão | | `invalid_card` | dados ou token do cartão não conferem, ou a conta não reconhece mais a cópia salva do cartão (Asaas: "CreditCardToken não encontrado") | gerar o token de novo; num cartão salvo, a SuyPay já tenta sozinha com o cartão do cofre | | `fraud_suspected` | barrado pela análise de risco da conta | confirmar os dados ou pedir Pix | | `risk_blocked` | barrado pela [Proteção](https://docs.suypay.com/protection.md) da SuyPay (lista de bloqueio, limites ou teste de cartões) | ver o motivo em `failure_reason`; ajustar em Proteção se foi engano | | `org_suspended` | a empresa está suspensa na SuyPay | falar com o suporte | | `invalid_document` | CPF ou CNPJ inválido | corrigir o documento | | `missing_document` / `missing_email` / `missing_phone` | a conta exige esse dado | enviar o dado do cliente | | `invalid_data` | a conta recusou algum campo | conferir os dados do cliente | | `invalid_credentials` | as chaves da conta pararam de funcionar | atualizar em Contas conectadas | | `account_not_enabled` | o recurso não está liberado na conta | pedir a liberação à empresa da conta | | `provider_unavailable` / `timeout` / `rate_limited` | a conta está fora do ar ou lenta | tentar de novo; a SuyPay já tenta a próxima conta | | `already_paid` | a cobrança já foi paga | nada | | `not_refundable` | a conta não devolve isso pela API | devolver pelo painel da conta | | `not_cancelable` | a conta não cancela isso pela API | cancelar pelo painel da conta ou esperar vencer | | `insufficient_balance` | a conta não tem saldo para o saque ou a devolução | conferir o saldo e o que está retido por MED | | `invalid_pix_key` | a chave Pix não confere com o tipo | corrigir a chave salva | | `payout_blocked` | saques bloqueados na conta (KYC, bloqueio do provedor) | resolver no painel da conta | | `limit_exceeded` | passa do limite de saque (da conta ou o limite de 24 horas da empresa) | sacar menos ou ajustar o limite | | `missing_scope` | a chave da conta não tem a permissão (por exemplo, de transferência) | criar uma chave com a permissão e atualizar a conta | | `restricted_key` | a sua chave SuyPay é **só cobranças** e a rota pede uma chave completa | usar uma chave completa no seu servidor | | `payouts_api_disabled` | saques pela API estão desligados | o dono liga em **Saques → Segurança** | ## Quando a SuyPay tenta a próxima conta Erros de **infraestrutura** (`provider_unavailable`, `timeout`, `rate_limited`) e chaves quebradas (`invalid_credentials`) fazem a SuyPay tentar a próxima conta na hora. Erros sobre a **venda** (cartão recusado, documento inválido) não: outra conta recusaria pelo mesmo motivo. Saques **nunca** trocam de conta nem se repetem sozinhos. Se a conta não responder, o saque fica com `uncertain: true` e a SuyPay consulta de novo, sem enviar outra vez. Veja [Saques](https://docs.suypay.com/payouts.md). --- # Cobranças Uma cobrança é um pedido de pagamento por Pix, boleto ou cartão. A SuyPay escolhe a conta, cria a cobrança nela e acompanha a situação até o fim. Para os campos de cada método, veja [Criar cobranças](https://docs.suypay.com/payments.md). ## Rotas | | Rota | | |---|---|---| | `POST` | `/payments` | criar ([campos](https://docs.suypay.com/payments.md)) | | `GET` | `/payments` | listar. Filtros: `status`, `method`, `provider`, `q` | | `GET` | `/payments/{id}` | ver uma, com histórico e tentativas | | `POST` | `/payments/{id}/refund` | devolver `{ amount? }` | | `POST` | `/payments/{id}/cancel` | cancelar uma cobrança que ainda não foi paga | | `POST` | `/payments/{id}/sync` | buscar a situação atual na conta | | `POST` | `/payments/{id}/fulfillment` | registrar a entrega (rastreio, acessos, nota): a prova de uma [contestação](https://docs.suypay.com/disputes.md#registre-a-entrega) | | `POST` | `/payments/{id}/simulate` | confirmar no teste pela conta de teste da SuyPay, pelo Asaas sandbox ou pelo Inter sandbox; exige chave de teste | | `GET` | `/customers` | clientes | ## Criar uma cobrança ```bash curl https://api.suypay.com/v1/payments \ -H "Authorization: Bearer suy_test_..." \ -H "Idempotency-Key: pedido-1042" \ -H "Content-Type: application/json" \ -d '{ "method": "pix", "amount": 4990, "customer": { "name": "Maria Silva" } }' ``` A resposta traz a conta escolhida em `provider`, o que o cliente precisa para pagar em `next_action` e a página para acompanhar a cobrança em `payment_url` (veja [Link de pagamento](https://docs.suypay.com/payment-links.md)). No cartão, o token precisa ser gerado antes pelo formulário da conta. Se omitir `method`, a resposta vem com `status: "requires_method"` e `payment_url`. Envie esse link ao cliente: ele escolhe entre as formas disponíveis. Para cartão escolhido no link, a Stripe abre seu Checkout seguro, onde também mostra Apple Pay e Google Pay quando elegíveis. O valor e os dados da cobrança são fixados na criação; o cliente só escolhe a forma. Para dividir a venda com [subcontas](https://docs.suypay.com/subaccounts.md), envie `splits`: `[{ "subaccount_id": "sub_...", "amount": 1000 }]` ou com `percentage` no lugar de `amount`. A cobrança vai pela conta das subcontas, e a resposta traz `splits` em centavos. Contas que exigem dados que você não mandou (e-mail, celular, CPF) são puladas, e a venda vai pela próxima. Se nenhuma servir, a cobrança volta com `status: "failed"`, `failure_reason` e `failure_code` (veja [Erros](https://docs.suypay.com/errors.md)). Num link de pagamento, uma tentativa recusada (cartão negado, conta fora do ar) não encerra a cobrança: ela volta para `requires_method`, com o motivo em `failure_code`, `failure_reason` e `last_error`, e você recebe `payment.attempt_failed`. O cliente tenta outro cartão ou outra forma no mesmo link. Cada tentativa fica em `attempts`. No cartão, mande também `device` quando tiver: `{ "user_agent": "...", "session_id": "id-da-visita", "fingerprints": { "mercadopago": "" } }`. A antifraude das contas usa esses dados para aprovar mais. A página de pagamento da SuyPay já manda sozinha. Veja [Proteção](https://docs.suypay.com/protection.md#antifraude-das-contas). Antes de chamar qualquer conta, a venda passa pela [Proteção](https://docs.suypay.com/protection.md). A cobrança traz o resultado em `risk` (`level`: `normal`, `elevated` ou `high`, e os sinais em `flags`); uma venda barrada volta com `failure_code: "risk_blocked"`. ## Devolver Sem `amount`, devolve tudo. Com `amount`, devolve só uma parte. Veja [Devoluções](https://docs.suypay.com/refunds.md). ## Cancelar Cancela uma cobrança que o cliente ainda não pagou: o QR code do Pix ou o boleto param de funcionar na conta e a cobrança fica com `status: "canceled"`. Chega o aviso `payment.canceled`. ```bash curl -X POST https://api.suypay.com/v1/payments/pay_.../cancel \ -H "Authorization: Bearer suy_test_..." ``` - Vale para links em `requires_method` e cobranças `pending` ou `processing`. Se já foi paga, use [Devolver](#devolver). - Se o cliente pagou um instante antes, a resposta é `409` com `code: "already_paid"` e a cobrança já aparece como paga. - A Appmax não deixa cancelar pela API: a resposta traz `code: "not_cancelable"`. Cancele pelo painel dela ou espere vencer. - Uma parcela de Pix Automático da Woovi não se cancela sozinha: cancele o Pix Automático. --- # Cartões salvos Para o passo a passo, veja o guia [Cartão salvo](https://docs.suypay.com/cards.md). | | Rota | | |---|---|---| | `GET` | `/v1/cards/config` | `script`, `publishable_key` e `allowed_origins` dos campos de cartão deste modo | | `PATCH` | `/v1/cards/config` | `allowed_origins`: os únicos sites que podem mostrar os campos (lista vazia: qualquer um). Chave completa | | `POST` | `/v1/cards` | salvar um cartão a partir do `tok_…` dos campos de cartão | | `GET` | `/v1/cards` | listar (`customer_id`, `limit`, `starting_after`) | | `GET` | `/v1/cards/{id}` | ver | | `DELETE` | `/v1/cards/{id}` | apagar (também do cofre) | ### Salvar | Campo | | | |---|---|---| | `vault_token` | obrigatório | o `tok_…` que `card.tokenize()` devolveu, em até 24 horas | | `holder_name` | obrigatório | nome impresso no cartão | | `customer` ou `customer_id` | | dono do cartão: cliente novo (ou o mesmo CPF/CNPJ) ou um que já existe | | `metadata` | | | Salvar aceita chave restrita de cobranças. Cobrar cartão salvo (`card.id` em `/v1/payments`) e apagar pedem chave completa. ### Objeto ```json { "id": "card_4Fh...", "object": "card", "mode": "test", "brand": "visa", "last4": "1111", "exp_month": 12, "exp_year": 2030, "holder_name": "ANA LIMA", "fingerprint": "Xk2...", "customer": "cus_...", "cvc_available_until": null, "metadata": {}, "created_at": "2026-10-19T17:30:00.000Z" } ``` `brand`: `visa`, `mastercard`, `elo`, `hipercard`, `american-express`, `diners-club`, `discover` ou `jcb`. `cvc_available_until`: até quando o CVV ainda existe (vem `null` depois da primeira aprovação ou passada 1 hora). ### Erros | `code` | | |---|---| | `card_expired` | o cartão está vencido | | `account_not_enabled` | o cofre não está ligado neste modo, ou nenhuma conta conectada cobra este cartão agora (por exemplo, as que restam pedem o CVV e ele já foi apagado) | | `invalid_card` | o cofre recusou o uso do cartão (apagado, ou CVV já apagado) | --- # Assinaturas e contestações Para o passo a passo, veja os guias [Pix Automático](https://docs.suypay.com/pix-automatico.md), [Assinatura por cartão](https://docs.suypay.com/card-subscriptions.md) e [Contestações](https://docs.suypay.com/disputes.md). ## Assinaturas (Pix Automático e cartão) | | Rota | | |---|---|---| | `POST` | `/v1/subscriptions` | criar: Pix Automático devolve o QR Code de aprovação, cartão já cobra o primeiro ciclo | | `GET` | `/v1/subscriptions` | listar (`status`, `limit`, `starting_after`) | | `GET` | `/v1/subscriptions/{id}` | ver, com os ciclos cobrados em `payments` | | `POST` | `/v1/subscriptions/{id}/charge` | cobrar um ciclo agora | | `POST` | `/v1/subscriptions/{id}/cancel` | cancelar | | `POST` | `/v1/subscriptions/{id}/simulate` | modo de teste, Pix Automático: aprovar como se fosse o cliente | ### Criar | Campo | | | |---|---|---| | `method` | | `pix_automatic` (padrão) ou `card` | | `card_id` | com `card` | o [cartão salvo](https://docs.suypay.com/cards.md) que paga os ciclos | | `customer` | obrigatório | `name`. No Pix Automático, também `document` (CPF/CNPJ); na Woovi, `address` completo | | `frequency` | obrigatório | `weekly`, `monthly`, `quarterly`, `semiannually` ou `annually` | | `amount` | | centavos por ciclo. Sem ele, o valor é variável | | `first_amount` | | centavos do primeiro ciclo, pago na aprovação. Padrão: `amount` | | `description` | | o cliente vê no app do banco | | `start_date` / `end_date` | | `AAAA-MM-DD`. Início padrão: hoje | | `retry` | | `true` (padrão). Pix: o banco tenta de novo até 3 vezes em 7 dias. Cartão: a SuyPay tenta de novo 3 vezes, 2 dias entre cada | | `provider_account_id` | | forçar uma conta (no cartão, todos os ciclos vão por ela) | | `metadata` | | copiado para cada ciclo | ### Objeto ```json { "id": "sub_8Hq...", "object": "subscription", "status": "pending", "amount": 4990, "first_amount": 4990, "frequency": "monthly", "start_date": "2026-10-18", "next_charge_date": "2026-11-18", "provider": "asaas", "approval": { "qr_code": "00020101...", "qr_code_base64": "iVBOR...", "url": null }, "customer": { "id": "cus_...", "name": "Ana Lima", "document": "52998224725" } } ``` `status`: `pending` (esperando o cliente ou a primeira cobrança), `active`, `past_due` (cartão: os ciclos continuaram falhando), `canceled`, `refused` ou `expired`. `approval` só vem no Pix Automático enquanto está `pending`. No cartão vêm também `method: "card"`, `card` (id do cartão) e `failed_attempts`. Ao criar por cartão, `latest_payment` traz a primeira cobrança. ### Cobrar um ciclo `amount` (obrigatório se o valor for variável). No Pix Automático, também `due_date` (`AAAA-MM-DD`, entre 2 e 10 dias úteis à frente); na Woovi os ciclos são criados pela própria Woovi, então esta rota não se aplica. No cartão, cobra agora; uma assinatura `past_due` volta a `active` se aprovar. Devolve a cobrança criada. ## Contestações | | Rota | | |---|---|---| | `GET` | `/v1/disputes` | listar (`status=open` traz as que esperam resposta; `payment_id`) | | `GET` | `/v1/disputes/{id}` | ver | | `POST` | `/v1/disputes/{id}/evidence` | responder: `text` e `urls` (links públicos das provas) | | `POST` | `/v1/payments/{id}/simulate-dispute` | modo de teste: abrir uma contestação | ```json { "id": "dp_2Kd...", "object": "dispute", "kind": "med", "status": "open", "amount": 8990, "reason": "Golpe", "due_at": "2026-10-25T12:00:00.000Z", "payment_id": "pay_3kXy...", "provider": "woovi" } ``` `kind`: `med` (Pix) ou `chargeback` (cartão). `status`: `open`, `under_review`, `won`, `lost` ou `canceled`. --- # Contas e regras Contas conectadas são as suas contas no Mercado Pago, Asaas, Efí e Stripe. Regras decidem por qual delas cada cobrança passa. Para o passo a passo, veja [Conectar contas](https://docs.suypay.com/connections.md) e [Regras](https://docs.suypay.com/rules.md). ## Rotas | | Rota | | |---|---|---| | `GET` | `/providers` | contas que dá para conectar | | `GET` / `POST` | `/provider-accounts` | listar / conectar | | `PATCH` / `DELETE` | `/provider-accounts/{id}` | alterar / desconectar | | `GET` / `POST` | `/routing-rules` | listar / criar regras | | `PATCH` / `DELETE` | `/routing-rules/{id}` | alterar / apagar | | `POST` | `/routing/simulate` | testar `{ method, amount, installments? }` | No campo `fees.card`, `pct` e `fixed` descrevem a taxa de 1x. Use `installments` para sobrescrever parcelas específicas, por exemplo `"installments": { "3": { "pct": 3.49, "fixed": 49 } }`. Os valores fixos são em centavos. Parcelas sem entrada própria usam a taxa de 1x; só são aceitas quantidades dentro do limite do provedor. Para contas cujo provedor oferece Pix Automático, use `pix_automatic_status` ao conectar ou editar: `"available"` (liberado nessa conta), `"unavailable"` (não liberado) ou `"unknown"` (ainda não confirmado, padrão). A resposta da conta devolve o mesmo campo. A SuyPay não tenta criar novas autorizações em contas marcadas como indisponíveis; uma autorização bem-sucedida atualiza a situação para `available`. ## Testar uma regra `POST /routing/simulate` responde por qual conta uma venda passaria, sem cobrar nada: Para cartão, envie `installments` de 1 a 21 para comparar as taxas daquela quantidade de parcelas. A resposta só inclui contas que aceitam esse parcelamento. ```bash curl -X POST https://api.suypay.com/v1/routing/simulate \ -H "Authorization: Bearer suy_test_..." \ -H "Content-Type: application/json" \ -d '{ "method": "boleto", "amount": 200000 }' ``` --- # Saques Saldo das contas e dinheiro saindo delas. Leia antes [Saques e transferências](https://docs.suypay.com/payouts.md): os saques pela API precisam estar ligados pelo dono e usam só destinos seguros. ## Rotas | | Rota | | |---|---|---| | `GET` | `/balances` | saldo de cada conta ativa no modo da chave | | `POST` | `/payouts` | sacar (exige `Idempotency-Key`) | | `GET` | `/payouts` | lista (`?status=`, `?provider_account_id=`) | | `GET` | `/payouts/:id` | um saque | | `POST` | `/payouts/:id/sync` | consultar a conta agora | | `GET` | `/payout-destinations` | chaves Pix salvas (mascaradas) | | `GET` | `/payout-settings` | `api_enabled` e `daily_limit` | Salvar chaves e mudar as regras é feito só no painel, pelo dono da empresa. ## Sacar ```bash curl https://api.suypay.com/v1/payouts \ -H "Authorization: Bearer suy_live_..." \ -H "Idempotency-Key: retirada-2026-10-18" \ -H "Content-Type: application/json" \ -d '{ "provider_account_id": "pa_...", "amount": 150000, "destination": { "type": "pix_key", "destination_id": "pdst_..." }, "description": "Retirada de outubro" }' ``` Para a conta cadastrada no provedor, use `"destination": { "type": "account" }`. ```json { "id": "po_...", "object": "payout", "status": "processing", "amount": 150000, "fee": 50, "provider": "wyvipay", "destination": { "type": "pix_key", "key_type": "email", "key": "m***@empresa.com.br", "label": "Conta da Maria" }, "uncertain": false, "failure_code": null, "failure_reason": null } ``` ## Quando a conta não responde A resposta vem com `status: "processing"` e `uncertain: true`. **Não crie outro saque.** A SuyPay consulta a conta de novo (pelo webhook dela, por `POST /payouts/:id/sync` e uma vez por dia). Nas contas que garantem que a mesma chave devolve a mesma transferência (Wyvi Pay, Pagmaster, ClownPay, Stripe), a SuyPay recupera o saque sozinha; nas outras, confira o extrato da conta. ## Avisos `payout.created`, `payout.updated`, `payout.paid`, `payout.failed`, `payout.canceled` e `payout_destination.created` chegam no seu [webhook](https://docs.suypay.com/webhooks.md) com o objeto `payout` (ou a chave salva, mascarada). --- # Subcontas e split Subcontas recebem parte das vendas (split). Leia antes [Subcontas e split](https://docs.suypay.com/subaccounts.md) para saber o que cada conta faz. ## Rotas | | Rota | | |---|---|---| | `POST` | `/subaccounts` | criar (admin) | | `GET` | `/subaccounts` | lista (`?status=`, `?provider_account_id=`, `?q=`) | | `GET` | `/subaccounts/:id` | uma subconta, com `totals` e as últimas vendas divididas em `splits` | | `PATCH` | `/subaccounts/:id` | mudar `name` e `metadata` na SuyPay | | `POST` | `/subaccounts/:id/sync` | consultar a situação na conta agora | | `POST` | `/subaccounts/:id/onboarding-link` | link de cadastro para o titular (Pagar.me, Asaas) | | `GET` | `/subaccounts/:id/balance` | saldo da subconta | | `POST` | `/subaccounts/:id/withdrawals` | sacar para o destino da subconta (exige `Idempotency-Key`) | | `GET` | `/subaccounts/:id/withdrawals` | saques dessa subconta | Chaves **só cobranças** não chegam a essas rotas. ## Criar ```bash curl https://api.suypay.com/v1/subaccounts \ -H "Authorization: Bearer suy_live_..." \ -H "Content-Type: application/json" \ -d '{ "provider_account_id": "pa_...", "type": "individual", "name": "João Souza", "document": "12345678909", "email": "joao@email.com", "phone": "11912345678", "birthdate": "1990-05-20", "mother_name": "Ana Souza", "occupation": "Vendedor", "monthly_income": 500000, "address": { "zip": "01310-100", "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP" }, "bank_account": { "bank": "341", "branch": "1234", "account": "123456", "account_digit": "7", "type": "checking" }, "transfer_interval": "weekly" }' ``` | Campo | | |---|---| | `provider_account_id` | a conta conectada onde a subconta fica | | `type` | `individual` (CPF) ou `company` (CNPJ). Sem ele, vem do tamanho do documento | | `name`, `document` | sempre | | `email`, `phone`, `birthdate` (AAAA-MM-DD), `mother_name`, `occupation`, `monthly_income` (centavos) | quando a conta pede | | `address` | `zip`, `street`, `number`, `neighborhood`, `city`, `state`, `complement` | | `bank_account` | `bank` (3 números), `branch`, `branch_digit`, `account`, `account_digit`, `type` (`checking`/`savings`), `holder_name`. Mesmo CPF/CNPJ da subconta | | `pix_key` | `{ "key_type": "cpf" \| "cnpj" \| "email" \| "phone" \| "random", "key" }` (Woovi) | | `company` | `trading_name` (razão social), `company_type` (Asaas: `MEI`, `LIMITED`, `INDIVIDUAL`, `ASSOCIATION`; Pagar.me: `LTDA`, `MEI`…), `founding_date`, `annual_revenue` (centavos) | | `partner` | sócio administrador de empresa (Pagar.me): mesmos campos de pessoa | | `transfer_interval` | repasse automático na Pagar.me: `daily`, `weekly` ou `monthly` | | `metadata` | até 20 chaves suas | Se faltar um campo que a conta exige, a resposta é `400` dizendo qual, em `error.param`. GET `/providers` mostra em `capabilities.subaccounts.requires` o que cada conta pede. ```json { "id": "sub_...", "object": "subaccount", "status": "pending", "status_detail": "Falta o titular concluir o cadastro (prova de vida). Já pode vender, mas não sacar.", "provider": "pagarme", "provider_account_id": "pa_...", "provider_subaccount_id": "re_...", "type": "individual", "name": "João Souza", "document": "12345678909", "details": { "bank_account": { "bank": "341", "branch": "1234", "account": "****456-7", "holder": "João Souza" } } } ``` No Asaas, a chave de API da subconta (que o Asaas mostra uma vez só) fica guardada com criptografia na SuyPay, para consultar a situação e o saldo dela. Ela nunca volta pela API. ## Link de cadastro ```bash curl -X POST https://api.suypay.com/v1/subaccounts/sub_.../onboarding-link -H "Authorization: Bearer suy_live_..." ``` ```json { "url": "https://...", "expires_at": "2026-10-19T17:00:00Z", "qr_code_base64": null } ``` ## Dividir uma cobrança Mande `splits` em [`POST /payments`](https://docs.suypay.com/api-payments.md): | Campo | | |---|---| | `subaccount_id` | `sub_...` ativa ou em cadastro | | `amount` | centavos do valor da venda, **ou** | | `percentage` | porcentagem do valor da venda (até duas casas) | Todas as subcontas precisam ser da mesma conta conectada, e as partes somam menos que o valor, deixando o bastante para a taxa. A cobrança devolvida traz `splits: [{ "subaccount_id", "amount" }]` em centavos. ## Sacar ```bash curl https://api.suypay.com/v1/subaccounts/sub_.../withdrawals \ -H "Authorization: Bearer suy_live_..." \ -H "Idempotency-Key: repasse-joao-2026-10" \ -H "Content-Type: application/json" \ -d '{ "amount": 150000 }' ``` A resposta é um objeto [`payout`](https://docs.suypay.com/api-payouts.md) com `subaccount_id` e `destination: { "type": "subaccount" }`. Na Woovi, `amount` é ignorado: o saque leva o saldo inteiro. A subconta precisa estar `active`. ## Avisos `subaccount.created` e `subaccount.updated` chegam no seu [webhook](https://docs.suypay.com/webhooks.md) com o objeto `subaccount`. Os saques avisam como qualquer saque (`payout.*`). --- # Avisos e relatórios Tudo o que acontece com uma cobrança vira um evento. Os eventos podem ser lidos pela API ou recebidos no seu sistema por [webhooks](https://docs.suypay.com/webhooks.md). ## Rotas | | Rota | | |---|---|---| | `GET` | `/events` | tudo que aconteceu | | `GET` / `POST` | `/webhook-endpoints` | endereços de aviso | | `GET` | `/analytics/overview` | resumo do período (`?start=&end=`) | | `POST` | `/reconciliation-runs` | conferir um período | ## Endereço de aviso de um bot Um endereço pode ouvir só as cobranças criadas por uma chave: mande `only_source` com `key:` e o id da chave. Assim cada bot da empresa recebe apenas o que é dele. ```bash curl https://api.suypay.com/v1/webhook-endpoints \ -H "Authorization: Bearer suy_live_..." \ -H "Content-Type: application/json" \ -d '{ "url": "https://meubot.com/suypay", "events": ["payment.succeeded"], "only_source": "key:key_..." }' ``` ## Conferir um período Veja [Conferência](https://docs.suypay.com/reconciliation.md) para o que é comparado e como rodar fora do horário.